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 (Phase 1)

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

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
statuses.read	List workflow statuses
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
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

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
  }
}