diff --git a/content/en/v1/api/_index.md b/content/en/v1/api/_index.md index 06e6d4f..fc25b17 100644 --- a/content/en/v1/api/_index.md +++ b/content/en/v1/api/_index.md @@ -55,4 +55,10 @@ You must call the API with a `POST` HTTP request. Kanboard supports batch requests, allowing you to make multiple API calls in a single HTTP request. This is particularly useful for mobile clients with higher network latency. +Response examples illustrate the structure of the returned data. Some examples show database values +as JSON strings, while an actual response can contain numbers or booleans instead. Responses can also +include fields not shown in an example. Check the response from your Kanboard installation when +building clients that require fixed JSON types. For example, a task's `is_active` field may be a +boolean with PostgreSQL or an integer with SQLite. + ## API Procedures diff --git a/content/en/v1/api/column_procedures.md b/content/en/v1/api/column_procedures.md index 9679c58..79096a9 100644 --- a/content/en/v1/api/column_procedures.md +++ b/content/en/v1/api/column_procedures.md @@ -28,7 +28,7 @@ Request example: } ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { @@ -36,25 +36,40 @@ Response example: "id": 887036325, "result": [ { - "id": "1", + "id": 1, "title": "Backlog", - "position": "1", - "project_id": "1", - "task_limit": "0" + "position": 1, + "project_id": 1, + "task_limit": 0, + "description": "", + "hide_in_dashboard": false }, { - "id": "2", + "id": 2, "title": "Ready", - "position": "2", - "project_id": "1", - "task_limit": "0" + "position": 2, + "project_id": 1, + "task_limit": 0, + "description": "", + "hide_in_dashboard": false }, { - "id": "3", + "id": 3, "title": "Work in progress", - "position": "3", - "project_id": "1", - "task_limit": "0" + "position": 3, + "project_id": 1, + "task_limit": 0, + "description": "", + "hide_in_dashboard": false + }, + { + "id": 4, + "title": "Done", + "position": 4, + "project_id": 1, + "task_limit": 0, + "description": "", + "hide_in_dashboard": false } ] } @@ -82,18 +97,20 @@ Request example: } ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { "jsonrpc": "2.0", "id": 1242049935, "result": { - "id": "2", - "title": "Youpi", - "position": "2", - "project_id": "1", - "task_limit": "5" + "id": 1, + "title": "Backlog", + "position": 1, + "project_id": 1, + "task_limit": 0, + "description": "", + "hide_in_dashboard": false } } ``` diff --git a/content/en/v1/api/comment_procedures.md b/content/en/v1/api/comment_procedures.md index 496911b..db29875 100644 --- a/content/en/v1/api/comment_procedures.md +++ b/content/en/v1/api/comment_procedures.md @@ -91,7 +91,7 @@ getAllComments - Parameters: - **task_id** (integer, required) - Result on success: **List of comments** -- Result on failure: **false** +- When no comments are found, the result is an **empty array** (`[]`). Request example: @@ -106,7 +106,7 @@ Request example: } ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { @@ -114,13 +114,17 @@ Response example: "id": 148484683, "result": [ { - "id": "1", - "date_creation": "1410882272", - "task_id": "1", - "user_id": "1", - "comment": "Comment #1", + "id": 1, + "date_creation": 1794435903, + "date_modification": 1794435903, + "task_id": 1, + "user_id": 1, + "comment": "Example comment", + "visibility": "app-user", "username": "admin", - "name": null + "name": null, + "email": null, + "avatar_path": null } ] } diff --git a/content/en/v1/api/external_task_link_procedures.md b/content/en/v1/api/external_task_link_procedures.md index b547d9f..30eb9d5 100644 --- a/content/en/v1/api/external_task_link_procedures.md +++ b/content/en/v1/api/external_task_link_procedures.md @@ -180,26 +180,26 @@ Request example: {"jsonrpc":"2.0","method":"getAllExternalTaskLinks","id":2069307223,"params":[9]} ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { "jsonrpc": "2.0", "result": [ { - "id": "1", - "link_type": "attachment", + "id": 1, + "link_type": "weblink", "dependency": "related", - "title": "New title", - "url": "http:\/\/localhost\/document.pdf", - "date_creation": "1466965256", - "date_modification": "1466965256", - "task_id": "9", - "creator_id": "0", + "title": "Example", + "url": "https://example.com/", + "date_creation": 1700000000, + "date_modification": 1700000000, + "task_id": 1, + "creator_id": 1, "creator_name": null, - "creator_username": null, + "creator_username": "admin", "dependency_label": "Related", - "type": "Attachment" + "type": "Web Link" } ], "id": 2069307223 diff --git a/content/en/v1/api/internal_task_link_procedures.md b/content/en/v1/api/internal_task_link_procedures.md index ad66803..4bf7063 100644 --- a/content/en/v1/api/internal_task_link_procedures.md +++ b/content/en/v1/api/internal_task_link_procedures.md @@ -139,7 +139,7 @@ Request example: } ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { @@ -147,18 +147,24 @@ Response example: "id": 810848359, "result": [ { - "id": "1", - "task_id": "3", + "id": 1, + "task_id": 2, "label": "relates to", - "title": "B", - "is_active": "1", - "project_id": "1", - "task_time_spent": "0", - "task_time_estimated": "0", - "task_assignee_id": "0", + "title": "Related task", + "is_active": true, + "project_id": 1, + "column_id": 1, + "color_id": "yellow", + "date_completed": null, + "date_started": 0, + "date_due": 0, + "task_time_spent": null, + "task_time_estimated": null, + "task_assignee_id": 0, "task_assignee_username": null, "task_assignee_name": null, - "column_title": "Backlog" + "column_title": "Backlog", + "project_name": "API check" } ] } diff --git a/content/en/v1/api/project_procedures.md b/content/en/v1/api/project_procedures.md index 5cf26a8..626bd17 100644 --- a/content/en/v1/api/project_procedures.md +++ b/content/en/v1/api/project_procedures.md @@ -69,28 +69,36 @@ Request example: } ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { "jsonrpc": "2.0", "id": 226760253, "result": { - "id": "1", - "name": "API test", - "is_active": "1", + "id": 1, + "name": "API check", + "is_active": true, "token": "", - "last_modified": "1436119135", - "is_public": "0", - "is_private": "0", - "default_swimlane": "Default swimlane", - "show_default_swimlane": "1", - "description": "test", + "last_modified": 1794435881, + "is_public": false, + "is_private": false, + "description": null, "identifier": "", + "start_date": "", + "end_date": "", + "owner_id": 1, + "priority_default": 0, + "priority_start": 0, + "priority_end": 3, + "email": null, + "predefined_email_subjects": null, + "per_swimlane_task_limits": false, + "task_limit": 0, + "enable_global_tags": true, "url": { - "board": "http:\/\/127.0.0.1:8000\/?controller=board&action=show&project_id=1", - "calendar": "http:\/\/127.0.0.1:8000\/?controller=calendar&action=show&project_id=1", - "list": "http:\/\/127.0.0.1:8000\/?controller=listing&action=show&project_id=1" + "board": "http://localhost/?controller=BoardViewController&action=show&project_id=1", + "list": "http://localhost/?controller=TaskListController&action=show&project_id=1" } } } @@ -138,7 +146,6 @@ Response example: "identifier": "", "url": { "board": "http:\/\/127.0.0.1:8000\/?controller=board&action=show&project_id=1", - "calendar": "http:\/\/127.0.0.1:8000\/?controller=calendar&action=show&project_id=1", "list": "http:\/\/127.0.0.1:8000\/?controller=listing&action=show&project_id=1" } } @@ -187,7 +194,6 @@ Response example: "identifier": "TEST", "url": { "board": "http:\/\/127.0.0.1:8000\/?controller=board&action=show&project_id=1", - "calendar": "http:\/\/127.0.0.1:8000\/?controller=calendar&action=show&project_id=1", "list": "http:\/\/127.0.0.1:8000\/?controller=listing&action=show&project_id=1" } } @@ -237,7 +243,6 @@ Response example: "email": "my_project@my_domain.tld", "url": { "board": "http:\/\/127.0.0.1:8000\/?controller=board&action=show&project_id=1", - "calendar": "http:\/\/127.0.0.1:8000\/?controller=calendar&action=show&project_id=1", "list": "http:\/\/127.0.0.1:8000\/?controller=listing&action=show&project_id=1" } } @@ -263,7 +268,7 @@ Request example: } ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { @@ -271,21 +276,29 @@ Response example: "id": 2134420212, "result": [ { - "id": "1", - "name": "API test", - "is_active": "1", + "id": 1, + "name": "API check", + "is_active": true, "token": "", - "last_modified": "1436119570", - "is_public": "0", - "is_private": "0", - "default_swimlane": "Default swimlane", - "show_default_swimlane": "1", + "last_modified": 1794435881, + "is_public": false, + "is_private": false, "description": null, "identifier": "", + "start_date": "", + "end_date": "", + "owner_id": 1, + "priority_default": 0, + "priority_start": 0, + "priority_end": 3, + "email": null, + "predefined_email_subjects": null, + "per_swimlane_task_limits": false, + "task_limit": 0, + "enable_global_tags": true, "url": { - "board": "http:\/\/127.0.0.1:8000\/?controller=board&action=show&project_id=1", - "calendar": "http:\/\/127.0.0.1:8000\/?controller=calendar&action=show&project_id=1", - "list": "http:\/\/127.0.0.1:8000\/?controller=listing&action=show&project_id=1" + "board": "http://localhost/?controller=BoardViewController&action=show&project_id=1", + "list": "http://localhost/?controller=TaskListController&action=show&project_id=1" } } ] diff --git a/content/en/v1/api/swimlane_procedures.md b/content/en/v1/api/swimlane_procedures.md index d518df6..7f92b3b 100644 --- a/content/en/v1/api/swimlane_procedures.md +++ b/content/en/v1/api/swimlane_procedures.md @@ -118,18 +118,20 @@ Request example: } ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { "jsonrpc": "2.0", "id": 131071870, "result": { - "id": "1", - "name": "Swimlane 1", - "position": "1", - "is_active": "1", - "project_id": "1" + "id": 1, + "name": "Default swimlane", + "position": 1, + "is_active": true, + "project_id": 1, + "description": "", + "task_limit": 0 } } ``` diff --git a/content/en/v1/api/task_file_procedures.md b/content/en/v1/api/task_file_procedures.md index 410f7e7..e91f45c 100644 --- a/content/en/v1/api/task_file_procedures.md +++ b/content/en/v1/api/task_file_procedures.md @@ -52,7 +52,7 @@ getAllTaskFiles - Parameters: - **task_id** (integer, required) - Result on success: **list of files** -- Result on failure: **false** +- When no files are found, the result is an **empty array** (`[]`). Request example: @@ -67,7 +67,7 @@ Request example: } ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { @@ -75,16 +75,17 @@ Response example: "id": 1880662820, "result": [ { - "id": "1", - "name": "My file", - "path": "1\/1\/0db4d0a897a4c852f6e12f0239d4805f7b4ab596", - "is_image": "0", - "task_id": "1", - "date": "1432509941", - "user_id": "0", - "size": "15", - "username": null, - "user_name": null + "id": 1, + "name": "example.txt", + "path": "tasks/1/37429b6c2e7b3a8cfce5fc5d081c0bf672d86583", + "is_image": false, + "task_id": 1, + "date": 1794435903, + "user_id": 1, + "size": 12, + "username": "admin", + "user_name": null, + "etag": "90d01f392ecef0bc5045164b8d8f12de" } ] } diff --git a/content/en/v1/api/task_metadata_procedures.md b/content/en/v1/api/task_metadata_procedures.md index 44518d2..863add4 100644 --- a/content/en/v1/api/task_metadata_procedures.md +++ b/content/en/v1/api/task_metadata_procedures.md @@ -12,8 +12,8 @@ getTaskMetadata - Purpose: **Get all metadata related to a task by task unique id** - Parameters: - **task_id** (integer, required) -- Result on success: **list of metadata** -- Result on failure: **empty array** +- Result on success: **object mapping metadata names to values** +- If the task has no metadata, the result is an **empty object** (`{}`). Request example to fetch all the metadata of a task: @@ -34,12 +34,10 @@ Response example: { "jsonrpc": "2.0", "id": 133280317, - "result": [ - { - "metaKey1": "metaValue1", - "metaKey2": "metaValue2" - } - ] + "result": { + "metaKey1": "metaValue1", + "metaKey2": "metaValue2" + } } ``` diff --git a/content/en/v1/api/task_procedures.md b/content/en/v1/api/task_procedures.md index 37bff0b..dc27bc3 100644 --- a/content/en/v1/api/task_procedures.md +++ b/content/en/v1/api/task_procedures.md @@ -93,43 +93,46 @@ Request example: } ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { "jsonrpc": "2.0", "id": 700738119, "result": { - "id": "1", - "title": "Task #1", + "id": 1, + "title": "API example", "description": "", - "date_creation": "1409963206", - "color_id": "blue", - "project_id": "1", - "column_id": "2", - "owner_id": "1", - "position": "1", - "is_active": "1", + "date_creation": 1794435850, + "color_id": "yellow", + "project_id": 1, + "column_id": 1, + "owner_id": 0, + "position": 1, + "is_active": true, "date_completed": null, - "score": "0", - "date_due": "0", - "category_id": "0", - "creator_id": "0", - "date_modification": "1409963206", - "reference": "", - "date_started": null, - "time_spent": "0", - "time_estimated": "0", - "swimlane_id": "0", - "date_moved": "1430875287", - "recurrence_status": "0", - "recurrence_trigger": "0", - "recurrence_factor": "0", - "recurrence_timeframe": "0", - "recurrence_basedate": "0", + "score": 0, + "date_due": 0, + "category_id": 0, + "creator_id": 1, + "date_modification": 1794435881, + "reference": "EXAMPLE-1", + "date_started": 0, + "time_spent": null, + "time_estimated": null, + "swimlane_id": 1, + "date_moved": 1794435850, + "recurrence_status": 0, + "recurrence_trigger": 0, + "recurrence_factor": 0, + "recurrence_timeframe": 0, + "recurrence_basedate": 0, "recurrence_parent": null, "recurrence_child": null, - "url": "http:\/\/127.0.0.1:8000\/?controller=task&action=show&task_id=1&project_id=1", + "priority": 0, + "external_provider": null, + "external_uri": null, + "url": "http://localhost/?controller=TaskViewController&action=show&task_id=1", "color": { "name": "Yellow", "background": "rgb(245, 247, 196)", @@ -158,48 +161,56 @@ Request example: "id": 1992081213, "params": { "project_id": 1, - "reference": "TICKET-1234" + "reference": "EXAMPLE-1" } } ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { "jsonrpc": "2.0", "id": 1992081213, "result": { - "id": "5", - "title": "Task with external ticket number", - "description": "[Link to my ticket](http:\/\/my-ticketing-system\/1234)", - "date_creation": "1434227446", + "id": 1, + "title": "API example", + "description": "", + "date_creation": 1794435850, "color_id": "yellow", - "project_id": "1", - "column_id": "1", - "owner_id": "0", - "position": "4", - "is_active": "1", + "project_id": 1, + "column_id": 1, + "owner_id": 0, + "position": 1, + "is_active": true, "date_completed": null, - "score": "0", - "date_due": "0", - "category_id": "0", - "creator_id": "0", - "date_modification": "1434227446", - "reference": "TICKET-1234", - "date_started": null, - "time_spent": "0", - "time_estimated": "0", - "swimlane_id": "0", - "date_moved": "1434227446", - "recurrence_status": "0", - "recurrence_trigger": "0", - "recurrence_factor": "0", - "recurrence_timeframe": "0", - "recurrence_basedate": "0", + "score": 0, + "date_due": 0, + "category_id": 0, + "creator_id": 1, + "date_modification": 1794435881, + "reference": "EXAMPLE-1", + "date_started": 0, + "time_spent": null, + "time_estimated": null, + "swimlane_id": 1, + "date_moved": 1794435850, + "recurrence_status": 0, + "recurrence_trigger": 0, + "recurrence_factor": 0, + "recurrence_timeframe": 0, + "recurrence_basedate": 0, "recurrence_parent": null, "recurrence_child": null, - "url": "http:\/\/127.0.0.1:8000\/?controller=task&action=show&task_id=5&project_id=1" + "priority": 0, + "external_provider": null, + "external_uri": null, + "url": "http://localhost/?controller=TaskViewController&action=show&task_id=1", + "color": { + "name": "Yellow", + "background": "rgb(245, 247, 196)", + "border": "rgb(223, 227, 45)" + } } } ``` @@ -229,7 +240,7 @@ Request example to fetch all tasks on the board: } ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { @@ -237,83 +248,43 @@ Response example: "id": 133280317, "result": [ { - "id": "1", - "title": "Task #1", + "id": 1, + "title": "API example", "description": "", - "date_creation": "1409961789", - "color_id": "blue", - "project_id": "1", - "column_id": "2", - "owner_id": "1", - "position": "1", - "is_active": "1", - "date_completed": null, - "score": "0", - "date_due": "0", - "category_id": "0", - "creator_id": "0", - "date_modification": "1409961789", - "reference": "", - "date_started": null, - "time_spent": "0", - "time_estimated": "0", - "swimlane_id": "0", - "date_moved": "1430783191", - "recurrence_status": "0", - "recurrence_trigger": "0", - "recurrence_factor": "0", - "recurrence_timeframe": "0", - "recurrence_basedate": "0", - "recurrence_parent": null, - "recurrence_child": null, - "priority": "0", - "external_provider": null, - "external_uri": null, - "url": "http:\/\/127.0.0.1:8000\/?controller=task&action=show&task_id=1&project_id=1", - "color": { - "name": "Blue", - "background": "rgb(219, 235, 255)", - "border": "rgb(168, 207, 255)" - } - }, - { - "id": "2", - "title": "Test", - "description": "", - "date_creation": "1409962115", - "color_id": "green", - "project_id": "1", - "column_id": "2", - "owner_id": "1", - "position": "2", - "is_active": "1", + "date_creation": 1794435850, + "color_id": "yellow", + "project_id": 1, + "column_id": 1, + "owner_id": 0, + "position": 1, + "is_active": true, "date_completed": null, - "score": "0", - "date_due": "0", - "category_id": "0", - "creator_id": "0", - "date_modification": "1409962115", - "reference": "", - "date_started": null, - "time_spent": "0", - "time_estimated": "0", - "swimlane_id": "0", - "date_moved": "1430783191", - "recurrence_status": "0", - "recurrence_trigger": "0", - "recurrence_factor": "0", - "recurrence_timeframe": "0", - "recurrence_basedate": "0", + "score": 0, + "date_due": 0, + "category_id": 0, + "creator_id": 1, + "date_modification": 1794435881, + "reference": "EXAMPLE-1", + "date_started": 0, + "time_spent": null, + "time_estimated": null, + "swimlane_id": 1, + "date_moved": 1794435850, + "recurrence_status": 0, + "recurrence_trigger": 0, + "recurrence_factor": 0, + "recurrence_timeframe": 0, + "recurrence_basedate": 0, "recurrence_parent": null, "recurrence_child": null, - "priority": "0", + "priority": 0, "external_provider": null, "external_uri": null, - "url": "http:\/\/127.0.0.1:8000\/?controller=task&action=show&task_id=2&project_id=1", + "url": "http://localhost/?controller=TaskViewController&action=show&task_id=1", "color": { - "name": "Green", - "background": "rgb(189, 244, 203)", - "border": "rgb(74, 227, 113)" + "name": "Yellow", + "background": "rgb(245, 247, 196)", + "border": "rgb(223, 227, 45)" } } ] diff --git a/content/en/v1/api/user_procedures.md b/content/en/v1/api/user_procedures.md index d0994c5..6d839b1 100644 --- a/content/en/v1/api/user_procedures.md +++ b/content/en/v1/api/user_procedures.md @@ -102,23 +102,34 @@ Request example: } ``` -Response example: +Response example (Kanboard 1.2.54, PostgreSQL 17, PHP 8.4): ```json { "jsonrpc": "2.0", "id": 1769674781, "result": { - "id": "1", - "username": "biloute", - "password": "$2y$10$dRs6pPoBu935RpmsrhmbjevJH5MgZ7Kr9QrnVINwwyZ3.MOwqg.0m", - "role": "app-user", - "is_ldap_user": "0", - "name": "", - "email": "", + "id": 1, + "username": "admin", + "is_ldap_user": false, + "name": null, + "email": null, "google_id": null, "github_id": null, - "notifications_enabled": "0" + "notifications_enabled": false, + "timezone": null, + "language": null, + "disable_login_form": false, + "twofactor_activated": false, + "notifications_filter": 4, + "nb_failed_login": 0, + "lock_expiration_date": 0, + "gitlab_id": null, + "role": "app-admin", + "is_active": true, + "avatar_path": null, + "filter": null, + "theme": "light" } } ```