API Documentation

Welcome to the API documentation. This guide will help you understand how to integrate the API into your applications using our REST interface.

Base URL

Direct all API requests to: /api/v1

Quick Start

Start using the API in just 5 minutes. Follow these steps:

1. Generate an API Key

Important: The API key is only shown once when created. Save it in a secure place!

2. Make Your First Request

Test the connection by getting a list of projects:

cURL

curl -X GET "/api/v1/projects" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Accept: application/json"

3. Explore the Response

A successful response will look like this:

JSON Response

{
  "status": "ok",
  "data": [
    {
      "id": 1,
      "name": "My first project",
      "description": "Project description",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Authentication

The API uses Bearer tokens for authentication. Every request must include a valid API key.

Authentication Methods

1. Authorization Header (recommended)

HTTP Header

Authorization: Bearer sk_live_your_api_key

2. Query Parameter (for quick tests)

URL

/api/v1/projects?key=sk_live_your_api_key

Key Types

sk_live_* - Production key, works with real data
sk_test_* - Test key (coming soon)

Permissions (Scopes)

Scope	Description
`read`	Read data (GET requests)
`write`	Create and update (POST, PUT)
`delete`	Delete resources (DELETE)
`admin`	Administrative operations

Rate Limits

The API has limits set to ensure fair access for all users.

Plan	Limit	Window
Default	1,000 requests	per hour

Rate Limit Headers

Each response contains information about the current limit status:

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 2024-01-15T11:00:00Z

Error Codes

The API uses standard HTTP status codes:

Code	Meaning	Description
`200`	OK	Request completed successfully
`201`	Created	Resource was created
`400`	Bad Request	Invalid request (missing parameters)
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Internal server error

Data Hierarchy

Data is hierarchical. Understanding this structure is key for proper API usage.

Project

→

Todolist

→

Todo

→

Comment

Project - Top level. Contains everything else.
Todolist - Category/list within a project (e.g., "Backend", "Frontend").
Todo - The actual task. Always belongs to a todolist.
Comment - Discussion on a task. Always belongs to a todo.

Practical Example

Want to create a task? First you need a todolist_id. You get that from a project. So the workflow is: Project → Todolist → Todo.

Projects

List Projects

GET /api/v1/projects

Returns a list of all projects the user has access to.

Query Parameters

Parameter	Type	Description
archived	boolean	optional Include archived projects

Get Project

GET /api/v1/projects/{id}

Returns detailed information about a specific project.

Path Parameters

Parameter	Type	Description
id	integer	required Project ID

Create Project

POST /api/v1/projects

Creates a new project.

Request Body

Parameter	Type	Description
name	string	required Project name
description	string	optional Project description

PHP Example

$response = $client->post('/api/v1/projects', [
    'json' => [
        'name' => 'New client website',
        'description' => 'Corporate website redesign'
    ]
]);

Update Project

PUT /api/v1/projects/{id}

Updates an existing project.

Delete Project

DELETE /api/v1/projects/{id}

Deletes a project and all its contents. This action is irreversible!

Requires scope delete.

Task Lists (Todolists)

List in Project

GET /api/v1/projects/{id}/todolists

Returns all task lists in the given project.

Create List

POST /api/v1/projects/{id}/todolists

Creates a new task list in the project.

Request Body

Parameter	Type	Description
name	string	required List name

Tasks (Todos)

List Tasks

GET /api/v1/todolists/{id}/todos

Returns all tasks in the given list.

Get Task

GET /api/v1/todos/{id}

Returns detailed information about a specific task.

Create Task

POST /api/v1/todolists/{id}/todos

Creates a new task in the list.

Request Body

Parameter	Type	Description
title	string	required Task name
description	string	optional Task description
due_date	date	optional Due date (YYYY-MM-DD)
assigned_to	integer	optional Assigned user ID

Complete PHP Example

// 1. Get todolist ID from project
$lists = $client->get('/api/v1/projects/1/todolists');
$todolistId = $lists['data'][0]['id'];

// 2. Create task in this todolist
$response = $client->post("/api/v1/todolists/{$todolistId}/todos", [
    'json' => [
        'title' => 'Implement new feature',
        'description' => 'Detailed task description...',
        'due_date' => '2024-02-01',
        'assigned_to' => 5
    ]
]);

$newTodo = json_decode($response->getBody(), true);
echo "Created task with ID: " . $newTodo['todo']['id'];

Update Task

PUT /api/v1/todos/{id}

Updates an existing task. You can update only the fields you want to change.

Delete Task

DELETE /api/v1/todos/{id}

Deletes a task. Requires scope delete.

Comments

List Comments

GET /api/v1/todos/{id}/comments

Returns all comments for a specific task, ordered by creation date (newest first).

Path Parameters

Parameter	Type	Description
id	integer	required Task ID

Response

Returns an array of comment objects, each containing:

id - Comment ID
content - Comment text (may contain HTML)
created_at - Creation timestamp
user - Author information (id, name, avatar)
attachments - Array of attached files

Add Comment

POST /api/v1/todos/{id}/comments

Adds a new comment to a task. Notifies subscribed users.

Path Parameters

Parameter	Type	Description
id	integer	required Task ID

Request Body

Parameter	Type	Description
content	string	required Comment text (supports HTML)
notify	boolean	optional Send notification to subscribers (default: true)

cURL Example

curl -X POST "/api/v1/todos/123/comments" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "This is my comment on the task."}'

Update Comment

PATCH /api/v1/comments/{id}

Updates an existing comment. Only the comment author can edit their comments.

Path Parameters

Parameter	Type	Description
id	integer	required Comment ID

Request Body

Parameter	Type	Description
content	string	required Updated comment text

Delete Comment

DELETE /api/v1/comments/{id}

Deletes a comment. Only the comment author or project admin can delete comments.

Requires scope delete. This action is irreversible.

Users

List Users

GET /api/v1/users

Returns a list of all users in the system that the authenticated user has access to see.

Response

Returns an array of user objects, each containing:

id - User ID
name - Full name
email - Email address
avatar - Avatar URL (if set)
role - User role (user, admin, superadmin)
is_active - Whether the user is active

cURL Example

curl -X GET "/api/v1/users" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Accept: application/json"

Project Members

List Members

GET /api/v1/projects/{id}/members

Returns a list of all members who have access to the specified project.

Path Parameters

Parameter	Type	Description
id	integer	required Project ID

Response

Returns an array of member objects with user details and their access role in the project.

Add Member

POST /api/v1/projects/{id}/members

Adds a user to the project, granting them access.

Path Parameters

Parameter	Type	Description
id	integer	required Project ID

Request Body

Parameter	Type	Description
user_id	integer	required ID of the user to add
role	string	optional Member role (default: member)

Remove Member

DELETE /api/v1/projects/{id}/members/{userId}

Removes a user from the project, revoking their access.

Path Parameters

Parameter	Type	Description
id	integer	required Project ID
userId	integer	required User ID to remove

Requires scope delete. The user will lose access to all project content.

Knowledge Base

List Articles

GET /api/v1/projects/{id}/knowledge

Returns all knowledge base articles in the specified project.

Path Parameters

Parameter	Type	Description
id	integer	required Project ID

Response

Returns an array of article objects, each containing:

id - Article ID
title - Article title
content - Article content (HTML)
created_at - Creation timestamp
updated_at - Last update timestamp
author - Author information
tags - Array of associated tags

Create Article

POST /api/v1/projects/{id}/knowledge

Creates a new knowledge base article in the project.

Path Parameters

Parameter	Type	Description
id	integer	required Project ID

Request Body

Parameter	Type	Description
title	string	required Article title
content	string	required Article content (supports HTML)
tags	array	optional Array of tag IDs to associate

cURL Example

curl -X POST "/api/v1/projects/1/knowledge" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Getting Started Guide", "content": "<p>Welcome to our knowledge base...</p>"}'

Update Article

PUT /api/v1/projects/{id}/knowledge/{postId}

Updates an existing knowledge base article.

Path Parameters

Parameter	Type	Description
id	integer	required Project ID
postId	integer	required Article ID

Request Body

Parameter	Type	Description
title	string	optional Updated title
content	string	optional Updated content

Delete Article

DELETE /api/v1/projects/{id}/knowledge/{postId}

Deletes a knowledge base article.

Path Parameters

Parameter	Type	Description
id	integer	required Project ID
postId	integer	required Article ID to delete

Requires scope delete. This action is irreversible and will also delete all associated comments.

Project Docs

List Docs

GET /api/v1/projects/{id}/docs

Returns documents in the selected project.

Path Parameters

Parameter	Type	Description
id	integer	required Project ID

Search Docs

GET /api/v1/projects/{id}/docs/search?q=changelog

Fulltext search in document title/content/description within one project.

Query Parameters

Parameter	Type	Description
q	string	required Search term (min 2 chars)
limit	integer	optional Max results (default 20, max 100)
include_content	boolean	optional Include full HTML content in response

Get Doc Content by Name

GET /api/v1/projects/{id}/docs/content?name=changelog

Returns HTML content of matching document title. If no matching document exists, returns false.

Compatibility Alias

Also available as: /project/{id}/docs/content?name=changelog

Create Doc

POST /api/v1/projects/{id}/docs

Creates a document in the project.

Request Body

Parameter	Type	Description
title	string	optional Document title (default: Untitled Document)
content	string	optional HTML content

Update Doc

PUT /api/v1/docs/{id}

Updates an existing document (title/content/flags).

Delete Doc

DELETE /api/v1/docs/{id}

Deletes (moves to trash) a document.

Requires scope delete.

Fulltext Search

General Fulltext (Algolia)

GET /api/v1/search?q=invoice&limit=20

Global permission-aware fulltext search over projects, task lists, todos and comments (Algolia-backed).

Query Parameters

Parameter	Type	Description
q	string	required Search term (min 2 chars)
limit	integer	optional Max hits (default 10, max 50)