Tilvin Developer API

Welcome to the Tilvin Developer API. Use this API to integrate Tilvin project management with your applications, automate workflows, and build custom tools.

Base URL

https://api.tilvin.com/api/v1

Current Version

The API is currently at v1. All endpoints are prefixed with /api/v1/.

Available Resources

Resource	Endpoints	Status
Projects	List, Get, Create, Update	Live
Tasks	List, Get, Create, Update	Live
Users	List	Live
Comments	Add	Live
Time Entries	Log	Live

Authentication

The Tilvin API uses Bearer token authentication. You can create API tokens from the Admin > Developer API section in your Tilvin account.

Using Your Token

Include your API token in the Authorization header of every request:

HTTP Header

Authorization: Bearer tlv_your_token_here

Example Request

cURL

curl -X GET https://api.tilvin.com/api/v1/projects \
     -H "Authorization: Bearer tlv_a1b2c3d4e5f6..."

Token Security

Important: Your API token is shown only once when created. Store it securely. If lost, create a new token and revoke the old one.

Scopes

Each token is created with specific permission scopes that control what it can access:

Scope	Description
projects.read	List and view project details
projects.write	Create and update projects
tasks.read	List and view task details
tasks.write	Create and update tasks
comments.write	Add discussion comments
users.read	List and view team members
timeentries.write	Log time entries

Errors

The API uses standard HTTP status codes and returns error details in a consistent JSON format.

Error Response Format

JSON

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided token is not valid."
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created - Resource successfully created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - Token lacks required scope
404	Not Found - Resource does not exist

Error Codes

Code	Description
MISSING_TOKEN	No Authorization header provided
INVALID_TOKEN	Token format is wrong or token not found
TOKEN_EXPIRED	Token has passed its expiry date
TOKEN_REVOKED	Token has been revoked by admin
CLIENT_INACTIVE	The API client is inactive or deleted
INSUFFICIENT_SCOPE	Token does not have the required scope
NOT_FOUND	The requested resource was not found
VALIDATION_ERROR	One or more required fields are missing or invalid

Pagination

List endpoints return paginated results. Use page and pageSize query parameters to navigate.

Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (starts at 1)
pageSize	integer	25	Items per page (max 100)

Response Format

JSON

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalItems": 42,
    "totalPages": 2
  }
}

List Projects

Returns a paginated list of all projects in your company.

GET /api/v1/projects projects.read

Query Parameters

Parameter	Type	Required	Description
search	string	Optional	Filter projects by name (partial match)
status	string	Optional	Filter by status: active or archived. Omit for all.
page	integer	Optional	Page number (default: 1)
pageSize	integer	Optional	Items per page (default: 25, max: 100)

Sample Request

cURL

curl -X GET "https://api.tilvin.com/api/v1/projects?status=active&page=1&pageSize=10" \
     -H "Authorization: Bearer tlv_a1b2c3d4e5f6..."

Response 200 OK

JSON

{
  "data": [
    {
      "id": "a8f2e4b1c3d5",
      "name": "Website Redesign",
      "description": "Complete overhaul of company website",
      "shortCode": "WR",
      "category": "Development",
      "projectImage": "abc123.png",
      "status": "active",
      "archived": false,
      "startDate": "2026-01-15T00:00:00",
      "endDate": "2026-06-30T00:00:00",
      "createdOn": "2026-01-10T14:30:00",
      "taskCount": 42
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalItems": 3,
    "totalPages": 1
  }
}

Get Project

Returns details of a single project by its unique ID.

GET /api/v1/projects/{id} projects.read

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The project's unique identifier (GUID)

Sample Request

cURL

curl -X GET "https://api.tilvin.com/api/v1/projects/a8f2e4b1c3d5" \
     -H "Authorization: Bearer tlv_a1b2c3d4e5f6..."

Response 200 OK

JSON

{
  "data": {
    "id": "a8f2e4b1c3d5",
    "name": "Website Redesign",
    "description": "Complete overhaul of company website",
    "shortCode": "WR",
    "category": "Development",
    "projectImage": "project_abc123.jpg",
    "status": "active",
    "archived": false,
    "startDate": "2026-01-15T00:00:00",
    "endDate": "2026-06-30T00:00:00",
    "createdOn": "2026-01-10T14:30:00",
    "taskCount": 42
  }
}

Error Response 404 Not Found

JSON

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found."
  }
}

Create Project

Creates a new project in your company.

POST /api/v1/projects projects.write

Request Body

Field	Type	Required	Description
name	string	Required	The project name
shortCode	string	Required	A short code identifier for the project (used in task numbers)
description	string	Optional	A description of the project
startDate	string	Optional	Project start date in ISO 8601 format (e.g. 2026-01-15)
endDate	string	Optional	Project end date in ISO 8601 format (e.g. 2026-06-30)

Sample Request

cURL

curl -X POST "https://api.tilvin.com/api/v1/projects" \
     -H "Authorization: Bearer tlv_a1b2c3d4e5f6..." \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Mobile App v2",
  "shortCode": "MA",
  "description": "Second version of the mobile application",
  "startDate": "2026-03-01",
  "endDate": "2026-09-30"
}'

Response 201 Created

JSON

{
  "data": {
    "id": "b9c3f5a2d4e6",
    "name": "Mobile App v2",
    "description": "Second version of the mobile application",
    "shortCode": "MA",
    "category": null,
    "projectImage": null,
    "status": "active",
    "archived": false,
    "startDate": "2026-03-01T00:00:00",
    "endDate": "2026-09-30T00:00:00",
    "createdOn": "2026-03-15T10:22:00",
    "taskCount": 0
  }
}

Error Response 400 Bad Request

JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'name' field is required."
  }
}

Update Project

Updates an existing project. Only the fields you include in the request body will be changed (partial update).

PUT /api/v1/projects/{id} projects.write

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The project's unique identifier (GUID)

Request Body

All fields are optional. Only include the fields you want to update.

Field	Type	Required	Description
name	string	Optional	The project name
description	string	Optional	Project description
shortCode	string	Optional	Project short code
startDate	string	Optional	Project start date in ISO 8601 format
endDate	string	Optional	Project end date in ISO 8601 format
archived	boolean	Optional	Set to true to archive the project, or false to unarchive

Sample Request

cURL

curl -X PUT "https://api.tilvin.com/api/v1/projects/a8f2e4b1c3d5" \
     -H "Authorization: Bearer tlv_a1b2c3d4e5f6..." \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Website Redesign v2",
  "endDate": "2026-08-31"
}'

Response 200 OK

JSON

{
  "data": {
    "id": "a8f2e4b1c3d5",
    "name": "Website Redesign v2",
    "description": "Complete overhaul of company website",
    "shortCode": "WR",
    "category": "Development",
    "projectImage": "project_abc123.jpg",
    "status": "active",
    "archived": false,
    "startDate": "2026-01-15T00:00:00",
    "endDate": "2026-08-31T00:00:00",
    "createdOn": "2026-01-10T14:30:00",
    "taskCount": 42
  }
}

Error Response 404 Not Found

JSON

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found."
  }
}

List Tasks

Returns a paginated list of tasks for a specific project.

GET /api/v1/projects/{id}/tasks tasks.read

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The project's unique identifier (GUID)

Query Parameters

Parameter	Type	Required	Description
search	string	Optional	Filter tasks by title (partial match)
status	string	Optional	Filter by status name (e.g. In Progress, Completed)
page	integer	Optional	Page number (default: 1)
pageSize	integer	Optional	Items per page (default: 25, max: 100)

Sample Request

cURL

curl -X GET "https://api.tilvin.com/api/v1/projects/a8f2e4b1c3d5/tasks?status=In%20Progress&page=1&pageSize=10" \
     -H "Authorization: Bearer tlv_a1b2c3d4e5f6..."

Response 200 OK

JSON

{
  "data": [
    {
      "id": "f1d2a3b4c5e6",
      "title": "Design homepage mockup",
      "description": "Create wireframes and high-fidelity mockups for the new homepage",
      "project": "Website Redesign",
      "projectShortCode": "WR",
      "taskNumber": "WR-42",
      "taskList": "Design",
      "status": "In Progress",
      "statusColor": "#f59e0b",
      "priority": "High",
      "assignedTo": ["jane@company.com", "bob@company.com"],
      "percentage": 60,
      "startDate": "2026-02-01T00:00:00",
      "endDate": "2026-02-28T00:00:00",
      "estimatedHrs": 20,
      "estimatedMins": 0,
      "createdOn": "2026-01-20T09:15:00",
      "subtaskCount": 5
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalItems": 42,
    "totalPages": 5
  }
}

Response Fields

Field	Type	Description
id	string	Unique task identifier
title	string	Task title
description	string	Task description
project	string	Project name
projectShortCode	string	Project short code
taskNumber	string	Human-readable task number (e.g. WR-42)
taskList	string	Name of the task list this task belongs to
status	string	Current status name
statusColor	string	Hex color code for the status
priority	string	Priority level name
assignedTo	array	Array of assigned user email addresses
percentage	integer	Completion percentage (0-100)
startDate	string	Task start date
endDate	string	Task end date
estimatedHrs	integer	Estimated hours
estimatedMins	integer	Estimated minutes
createdOn	string	Date and time the task was created
subtaskCount	integer	Number of subtasks

Get Task

Returns details of a single task by its unique ID.

GET /api/v1/tasks/{id} tasks.read

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The task's unique identifier (GUID)

Sample Request

cURL

curl -X GET "https://api.tilvin.com/api/v1/tasks/f1d2a3b4c5e6" \
     -H "Authorization: Bearer tlv_a1b2c3d4e5f6..."

Response 200 OK

JSON

{
  "data": {
    "id": "f1d2a3b4c5e6",
    "title": "Design homepage mockup",
    "description": "Create wireframes and high-fidelity mockups for the new homepage",
    "project": "Website Redesign",
    "projectShortCode": "WR",
    "taskNumber": "WR-42",
    "taskList": "Design",
    "status": "In Progress",
    "statusColor": "#f59e0b",
    "priority": "High",
    "assignedTo": ["jane@company.com", "bob@company.com"],
    "percentage": 60,
    "startDate": "2026-02-01T00:00:00",
    "endDate": "2026-02-28T00:00:00",
    "estimatedHrs": 20,
    "estimatedMins": 0,
    "createdOn": "2026-01-20T09:15:00",
    "subtaskCount": 5
  }
}

Error Response 404 Not Found

JSON

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Task not found."
  }
}

Create Task

Creates a new task. The project can be specified by name or short code. All name-based lookups (project, status, priority, taskList) are validated and will return an error if the referenced item is not found.

POST /api/v1/tasks tasks.write

Request Body

Field	Type	Required	Description
project	string	Required	Project name or short code (e.g. Website Redesign or WR)
title	string	Required	The task title
description	string	Optional	A description of the task
assignedTo	string	Optional	Email address of the user to assign
priority	string	Optional	Priority name (e.g. High, Medium, Low)
status	string	Optional	Status name (e.g. New, In Progress)
taskList	string	Optional	Task list name to place the task in
startDate	string	Optional	Task start date in ISO 8601 format
endDate	string	Optional	Task end date in ISO 8601 format
estimatedHrs	integer	Optional	Estimated hours for the task
estimatedMins	integer	Optional	Estimated minutes for the task

Note: The project, priority, status, and taskList fields use name-based lookups. If the specified name or short code does not match an existing record, the API will return a 400 error.

Sample Request

cURL

curl -X POST "https://api.tilvin.com/api/v1/tasks" \
     -H "Authorization: Bearer tlv_a1b2c3d4e5f6..." \
     -H "Content-Type: application/json" \
     -d '{
  "project": "WR",
  "title": "Implement user login page",
  "description": "Build the login page with email and password fields",
  "assignedTo": "jane@company.com",
  "priority": "High",
  "status": "New",
  "taskList": "Development",
  "startDate": "2026-03-15",
  "endDate": "2026-03-22",
  "estimatedHrs": 8,
  "estimatedMins": 0
}'

Response 201 Created

JSON

{
  "data": {
    "id": "e7a8b9c0d1f2",
    "title": "Implement user login page",
    "description": "Build the login page with email and password fields",
    "project": "Website Redesign",
    "projectShortCode": "WR",
    "taskNumber": "WR-43",
    "taskList": "Development",
    "status": "New",
    "statusColor": "#6b7280",
    "priority": "High",
    "assignedTo": ["jane@company.com"],
    "percentage": 0,
    "startDate": "2026-03-15T00:00:00",
    "endDate": "2026-03-22T00:00:00",
    "estimatedHrs": 8,
    "estimatedMins": 0,
    "createdOn": "2026-03-15T11:00:00",
    "subtaskCount": 0
  }
}

Error Response 400 Bad Request

JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Project 'XYZ' not found."
  }
}

Update Task

Updates an existing task. Only the fields you include in the request body will be changed (partial update).

PUT /api/v1/tasks/{id} tasks.write

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The task's unique identifier (GUID)

Request Body

All fields are optional. Only include the fields you want to update.

Field	Type	Required	Description
title	string	Optional	The task title
description	string	Optional	Task description
assignedTo	string	Optional	Email address of the user to assign
priority	string	Optional	Priority name
status	string	Optional	Status name
taskList	string	Optional	Task list name
startDate	string	Optional	Task start date in ISO 8601 format
endDate	string	Optional	Task end date in ISO 8601 format
estimatedHrs	integer	Optional	Estimated hours
estimatedMins	integer	Optional	Estimated minutes

Sample Request

cURL

curl -X PUT "https://api.tilvin.com/api/v1/tasks/f1d2a3b4c5e6" \
     -H "Authorization: Bearer tlv_a1b2c3d4e5f6..." \
     -H "Content-Type: application/json" \
     -d '{
  "status": "Completed",
  "priority": "Low"
}'

Response 200 OK

JSON

{
  "data": {
    "id": "f1d2a3b4c5e6",
    "title": "Design homepage mockup",
    "description": "Create wireframes and high-fidelity mockups for the new homepage",
    "project": "Website Redesign",
    "projectShortCode": "WR",
    "taskNumber": "WR-42",
    "taskList": "Design",
    "status": "Completed",
    "statusColor": "#10b981",
    "priority": "Low",
    "assignedTo": ["jane@company.com", "bob@company.com"],
    "percentage": 60,
    "startDate": "2026-02-01T00:00:00",
    "endDate": "2026-02-28T00:00:00",
    "estimatedHrs": 20,
    "estimatedMins": 0,
    "createdOn": "2026-01-20T09:15:00",
    "subtaskCount": 5
  }
}

Error Response 404 Not Found

JSON

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Task not found."
  }
}

List Users

Returns a list of all users in your company, including both active and inactive users.

GET /api/v1/users users.read

Query Parameters

Parameter	Type	Required	Description
search	string	Optional	Filter users by name or email (partial match)

Sample Request

cURL

curl -X GET "https://api.tilvin.com/api/v1/users?search=jane" \
     -H "Authorization: Bearer tlv_a1b2c3d4e5f6..."

Response 200 OK

JSON

{
  "data": [
    {
      "id": "c4d5e6f7a8b9",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane@company.com",
      "active": true,
      "companyName": "Acme Corp",
      "roles": ["Project Manager", "Team Member"],
      "skills": ["UI Design", "Frontend Development"]
    },
    {
      "id": "d5e6f7a8b9c0",
      "firstName": "Bob",
      "lastName": "Johnson",
      "email": "bob@company.com",
      "active": true,
      "companyName": "Acme Corp",
      "roles": ["Team Member"],
      "skills": ["Backend Development", "DevOps"]
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Unique user identifier
firstName	string	User's first name
lastName	string	User's last name
email	string	User's email address
active	boolean	Whether the user account is active
companyName	string	The user's company name
roles	array	Array of role names assigned to the user
skills	array	Array of skill names associated with the user

Add Comment

Adds a discussion comment to a task.

POST /api/v1/tasks/{id}/comments comments.write

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The task's unique identifier (GUID)

Request Body

Field	Type	Required	Description
text	string	Required	The comment text
userEmail	string	Optional	Email of the user posting the comment. Defaults to the API token creator if omitted.

Sample Request

cURL

curl -X POST "https://api.tilvin.com/api/v1/tasks/f1d2a3b4c5e6/comments" \
     -H "Authorization: Bearer tlv_a1b2c3d4e5f6..." \
     -H "Content-Type: application/json" \
     -d '{
  "text": "The mockups are ready for review. Please check the attached files."
}'

Response 201 Created

JSON

{
  "data": {
    "id": "a1b2c3d4e5f6",
    "text": "The mockups are ready for review. Please check the attached files.",
    "userEmail": "jane@company.com",
    "userName": "Jane Smith",
    "createdOn": "2026-03-15T14:30:00"
  }
}

Error Response 400 Bad Request

JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'text' field is required."
  }
}

Error Response 404 Not Found

JSON

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Task not found."
  }
}

Log Time

Logs a time entry against a task for time tracking and billing purposes.

POST /api/v1/tasks/{id}/time timeentries.write

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The task's unique identifier (GUID)

Request Body

Field	Type	Required	Description
date	string	Required	The date the work was performed in ISO 8601 format (e.g. 2026-03-15)
hours	integer	Optional	Number of hours worked
minutes	integer	Optional	Number of minutes worked
description	string	Optional	Description of the work performed
isBillable	boolean	Optional	Whether this time is billable (defaults to false)
userEmail	string	Optional	Email of the user who performed the work. Defaults to the API token creator if omitted.

Sample Request

cURL

curl -X POST "https://api.tilvin.com/api/v1/tasks/f1d2a3b4c5e6/time" \
     -H "Authorization: Bearer tlv_a1b2c3d4e5f6..." \
     -H "Content-Type: application/json" \
     -d '{
  "date": "2026-03-15",
  "hours": 3,
  "minutes": 30,
  "description": "Worked on homepage mockup revisions",
  "isBillable": true
}'

Response 201 Created

JSON

{
  "data": {
    "id": "b2c3d4e5f6a7",
    "date": "2026-03-15T00:00:00",
    "hours": 3,
    "minutes": 30,
    "description": "Worked on homepage mockup revisions",
    "isBillable": true,
    "userEmail": "jane@company.com",
    "userName": "Jane Smith",
    "createdOn": "2026-03-15T14:45:00"
  }
}

Error Response 400 Bad Request

JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'date' field is required."
  }
}

Error Response 404 Not Found

JSON

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Task not found."
  }
}