OpenAPI contract reference¶
Source: resources/openapi.yaml (3.1.0, API version 1.0.0). This page is generated from the uploaded contract and describes its formal HTTP surface.
OpenAPI server value: /api/v1. The server value is relative; the SDK therefore requires a user-supplied deployment URL.
GET /organizations/{organization}¶
Read organization
Requires organization:read.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
organization |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
200 |
Organization |
401 |
Invalid credential |
403 |
Wrong organization or scope |
GET /organizations/{organization}/projects¶
List projects
Requires projects:read.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
organization |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
200 |
Project list |
POST /organizations/{organization}/projects¶
Create project
Requires projects:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
organization |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
name |
yes | string; maxLength 180 |
key |
yes | string; maxLength 12 |
description |
no | string |
Responses¶
| Status | Description |
|---|---|
201 |
Project created |
422 |
Validation failure |
GET /projects/{project}¶
Read project
Requires projects:read.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
200 |
Project |
PATCH /projects/{project}¶
Update project
Requires projects:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
name |
no | string; maxLength 180 |
description |
no | string |
archived |
no | boolean |
Responses¶
| Status | Description |
|---|---|
200 |
Updated project |
422 |
Validation failure |
DELETE /projects/{project}¶
Soft-delete project
Requires projects:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
204 |
Deleted |
GET /projects/{project}/members¶
List project members
Requires projects:read. Includes explicit project members and organization owners/admins.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
200 |
Member list |
GET /projects/{project}/labels¶
List project labels
Requires projects:read.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
200 |
Label list |
GET /projects/{project}/boards¶
List project boards
Requires boards:read.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
200 |
Board list |
POST /projects/{project}/boards¶
Create project board
Requires boards:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
name |
yes | string; maxLength 120 |
color |
no | string |
wip_limit |
no | integer |
is_done |
no | boolean |
Responses¶
| Status | Description |
|---|---|
201 |
Board created |
422 |
Validation failure |
PUT /projects/{project}/boards/reorder¶
Reorder project boards
Requires boards:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
board_ids |
yes | array |
Responses¶
| Status | Description |
|---|---|
200 |
Reordered board list |
422 |
Invalid board list |
PATCH /boards/{board}¶
Update board
Requires boards:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
board |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
name |
no | string; maxLength 120 |
color |
no | string |
wip_limit |
no | integer |
is_done |
no | boolean |
is_hidden |
no | boolean |
Responses¶
| Status | Description |
|---|---|
200 |
Updated board |
DELETE /boards/{board}¶
Soft-delete board
Requires boards:write. If tickets exist, move_to_board_id is required.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
board |
path | yes | string |
JSON request body¶
Body required: no.
| Property | Required | Schema |
|---|---|---|
move_to_board_id |
no | string |
Responses¶
| Status | Description |
|---|---|
204 |
Deleted |
422 |
Invalid target or WIP limit exceeded |
GET /projects/{project}/tickets¶
List project tickets
Requires tickets:read.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string | |
board_id |
query | no | string | |
q |
query | no | string | |
per_page |
query | no | integer; min 1; max 200; default 50 |
Responses¶
| Status | Description |
|---|---|
200 |
Paginated ticket list |
POST /projects/{project}/tickets¶
Create ticket
Requires tickets:write. Choose board_id or board_slug. The API credential is recorded as the ticket creator and its name will appear in the UI instead of the user who provisioned it.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
board_id |
no | string |
board_slug |
no | string |
title |
yes | string; maxLength 500 |
description_html |
no | string |
priority |
no | string enum: lowest, low, normal, high, highest, critical |
due_at |
no | string |
assignee_ids |
no | array |
label_ids |
no | array |
Responses¶
| Status | Description |
|---|---|
201 |
Ticket created |
422 |
Validation, relation, or WIP-limit failure |
PUT /projects/{project}/tickets/reorder¶
Reorder tickets inside a board
Requires tickets:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
board_id |
yes | string |
ticket_ids |
yes | array |
Responses¶
| Status | Description |
|---|---|
204 |
Reordered |
422 |
Invalid ticket list |
GET /projects/{project}/analytics¶
Read project analytics
Requires analytics:read.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
200 |
Project analytics |
GET /tickets/{ticket}¶
Read ticket
Requires tickets:read.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
ticket |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
200 |
Ticket detail |
PATCH /tickets/{ticket}¶
Update ticket
Requires tickets:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
ticket |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
title |
no | string; maxLength 500 |
description_html |
no | string |
priority |
no | string enum: lowest, low, normal, high, highest, critical |
due_at |
no | string |
assignee_ids |
no | array |
label_ids |
no | array |
archived |
no | boolean |
Responses¶
| Status | Description |
|---|---|
200 |
Updated ticket |
DELETE /tickets/{ticket}¶
Soft-delete ticket
Requires tickets:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
ticket |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
204 |
Deleted |
POST /tickets/{ticket}/move¶
Move a ticket to another board
Requires tickets:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
ticket |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
board_id |
yes | string |
position |
no | integer; min 0 |
Responses¶
| Status | Description |
|---|---|
200 |
Moved ticket |
422 |
Invalid board or WIP limit reached |
POST /tickets/{ticket}/comments¶
Create ticket comment
Requires comments:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
ticket |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
body_html |
yes | string; maxLength 200000 |
Responses¶
| Status | Description |
|---|---|
201 |
Comment created |
GET /organizations/{organization}/documents¶
List organization documents
Requires documents:read. Supports optional project, status, search, tag, and pagination filters.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
organization |
path | yes | string | |
project_id |
query | no | string | |
status |
query | no | string enum: draft, published | |
q |
query | no | string | |
tags |
query | no | string | Comma-separated tag names. Multiple names use match-all filtering. |
per_page |
query | no | integer; min 1; max 200; default 50 |
Responses¶
| Status | Description |
|---|---|
200 |
Paginated document list |
POST /organizations/{organization}/documents¶
Create document
Requires documents:write. The API credential is recorded as the document author and its name will appear in the UI instead of the user who provisioned it.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
organization |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
project_id |
no | string |
title |
yes | string; maxLength 500 |
caption |
no | string |
content_html |
no | string |
status |
no | string enum: draft, published; default draft |
editor_ids |
no | array |
tag_names |
no | array |
Responses¶
| Status | Description |
|---|---|
201 |
Document created |
422 |
Validation failure |
GET /documents/{document}¶
Read document
Requires documents:read.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
document |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
200 |
Document detail |
PATCH /documents/{document}¶
Update document
Requires documents:write. Can update publication state, archive state, project scope, content, and editor membership.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
document |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
project_id |
no | string |
title |
no | string; maxLength 500 |
caption |
no | string |
content_html |
no | string |
status |
no | string enum: draft, published |
archived |
no | boolean |
editor_ids |
no | array |
tag_names |
no | array |
Responses¶
| Status | Description |
|---|---|
200 |
Document updated |
422 |
Validation failure |
DELETE /documents/{document}¶
Soft-delete document
Requires documents:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
document |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
204 |
Document soft-deleted |
POST /documents/{document}/comments¶
Create document comment
Requires document_comments:write.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
document |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
body_html |
yes | string; maxLength 200000 |
Responses¶
| Status | Description |
|---|---|
201 |
Comment created |
422 |
Validation failure |
POST /organizations/{organization}/notifications¶
Send organization notifications
Requires notifications:write. Recipients must belong to the credential organization.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
organization |
path | yes | string |
JSON request body¶
Body required: yes.
| Property | Required | Schema |
|---|---|---|
user_ids |
yes | array |
title |
yes | string; maxLength 180 |
body |
yes | string; maxLength 2000 |
url |
no | string |
Responses¶
| Status | Description |
|---|---|
201 |
Notifications queued/sent |
422 |
Invalid recipient or URL |
GET /projects/{project}/tags¶
List used project tags
Requires projects:read. Returns tags currently assigned to at least one ticket.
Parameters¶
| Name | Location | Required | Schema | Description |
|---|---|---|---|---|
project |
path | yes | string |
Responses¶
| Status | Description |
|---|---|
200 |
Used project tags with ticket counts |