Full OpenAPI contract reference

This document is generated from resources/openapi.yaml. It defines the detailed API contract.

OpenAPI version: 3.1.0
API title: Okatana External API
API version: 1.0.0
Server base in source: /api/v1

The source server is relative. The SDK combines it with the deployment URL that the caller must configure.

1. GET /organizations/{organization}

Summary: Read organization

Requires organization:read.

Parameters

Name	In	Required	Type	Constraints
organization	path	yes	string	—

Responses

Status	Description
200	Organization
401	Invalid credential
403	Wrong organization or scope

2. GET /organizations/{organization}/projects

Summary: List projects

Requires projects:read.

Parameters

Name	In	Required	Type	Constraints
organization	path	yes	string	—

Responses

Status	Description
200	Project list

3. POST /organizations/{organization}/projects

Summary: Create project

Requires projects:write.

Parameters

Name	In	Required	Type	Constraints
organization	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
name	yes	string	max length 180
key	yes	string	max length 12
description	no	string / null	max length 5000

Responses

Status	Description
201	Project created
422	Validation failure

4. GET /projects/{project}

Summary: Read project

Requires projects:read.

Parameters

Name	In	Required	Type	Constraints
project	path	yes	string	—

Responses

Status	Description
200	Project

5. PATCH /projects/{project}

Summary: Update project

Requires projects:write.

Parameters

Name	In	Required	Type	Constraints
project	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
name	no	string	max length 180
description	no	string / null	max length 5000
archived	no	boolean	—

Responses

Status	Description
200	Updated project
422	Validation failure

6. DELETE /projects/{project}

Summary: Soft-delete project

Requires projects:write.

Parameters

Name	In	Required	Type	Constraints
project	path	yes	string	—

Responses

Status	Description
204	Deleted

7. GET /projects/{project}/members

Summary: List project members

Requires projects:read. Includes explicit project members and organization owners/admins.

Parameters

Name	In	Required	Type	Constraints
project	path	yes	string	—

Responses

Status	Description
200	Member list

8. GET /projects/{project}/labels

Summary: List project labels

Requires projects:read.

Parameters

Name	In	Required	Type	Constraints
project	path	yes	string	—

Responses

Status	Description
200	Label list

9. GET /projects/{project}/boards

Summary: List project boards

Requires boards:read.

Parameters

Name	In	Required	Type	Constraints
project	path	yes	string	—

Responses

Status	Description
200	Board list

10. POST /projects/{project}/boards

Summary: Create project board

Requires boards:write.

Parameters

Name	In	Required	Type	Constraints
project	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
name	yes	string	max length 120
color	no	string / null	max length 32
wip_limit	no	integer / null	min 1
is_done	no	boolean	—

Responses

Status	Description
201	Board created
422	Validation failure

11. PUT /projects/{project}/boards/reorder

Summary: Reorder project boards

Requires boards:write.

Parameters

Name	In	Required	Type	Constraints
project	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
board_ids	yes	array<string>	—

Responses

Status	Description
200	Reordered board list
422	Invalid board list

12. PATCH /boards/{board}

Summary: Update board

Requires boards:write.

Parameters

Name	In	Required	Type	Constraints
board	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
name	no	string	max length 120
color	no	string / null	max length 32
wip_limit	no	integer / null	min 1
is_done	no	boolean	—
is_hidden	no	boolean	—

Responses

Status	Description
200	Updated board

13. DELETE /boards/{board}

Summary: Soft-delete board

Requires boards:write. If tickets exist, move_to_board_id is required.

Parameters

Name	In	Required	Type	Constraints
board	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
move_to_board_id	no	string	—

Responses

Status	Description
204	Deleted
422	Invalid target or WIP limit exceeded

14. GET /projects/{project}/tickets

Summary: List project tickets

Requires tickets:read.

Parameters

Name	In	Required	Type	Constraints
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

15. POST /projects/{project}/tickets

Summary: 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	In	Required	Type	Constraints
project	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
board_id	no	string	—
board_slug	no	string	—
title	yes	string	max length 500
description_html	no	string / null	max length 200000
priority	no	string	one of: lowest, low, normal, high, highest, critical
due_at	no	string / null	format date-time
assignee_ids	no	array<string>	—
label_ids	no	array<string>	—

Responses

Status	Description
201	Ticket created
422	Validation

16. PUT /projects/{project}/tickets/reorder

Summary: Reorder tickets inside a board

Requires tickets:write.

Parameters

Name	In	Required	Type	Constraints
project	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
board_id	yes	string	—
ticket_ids	yes	array<string>	—

Responses

Status	Description
204	Reordered
422	Invalid ticket list

17. GET /projects/{project}/analytics

Summary: Read project analytics

Requires analytics:read.

Parameters

Name	In	Required	Type	Constraints
project	path	yes	string	—

Responses

Status	Description
200	Project analytics

18. GET /tickets/{ticket}

Summary: Read ticket

Requires tickets:read.

Parameters

Name	In	Required	Type	Constraints
ticket	path	yes	string	—

Responses

Status	Description
200	Ticket detail

19. PATCH /tickets/{ticket}

Summary: Update ticket

Requires tickets:write.

Parameters

Name	In	Required	Type	Constraints
ticket	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
title	no	string	max length 500
description_html	no	string / null	max length 200000
priority	no	string	one of: lowest, low, normal, high, highest, critical
due_at	no	string / null	format date-time
assignee_ids	no	array<string>	—
label_ids	no	array<string>	—
archived	no	boolean	—

Responses

Status	Description
200	Updated ticket

20. DELETE /tickets/{ticket}

Summary: Soft-delete ticket

Requires tickets:write.

Parameters

Name	In	Required	Type	Constraints
ticket	path	yes	string	—

Responses

Status	Description
204	Deleted

21. POST /tickets/{ticket}/move

Summary: Move a ticket to another board

Requires tickets:write.

Parameters

Name	In	Required	Type	Constraints
ticket	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
board_id	yes	string	—
position	no	integer	min 0

Responses

Status	Description
200	Moved ticket
422	Invalid board or WIP limit reached

22. POST /tickets/{ticket}/comments

Summary: Create ticket comment

Requires comments:write.

Parameters

Name	In	Required	Type	Constraints
ticket	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
body_html	yes	string	max length 200000

Responses

Status	Description
201	Comment created

23. GET /organizations/{organization}/documents

Summary: List organization documents

Requires documents:read. Supports optional project, status, search, tag, and pagination filters.

Parameters

Name	In	Required	Type	Constraints
organization	path	yes	string	—
project_id	query	no	string	—
status	query	no	string	one of: draft, published
q	query	no	string	—
tags	query	no	string	—
per_page	query	no	integer	min 1; max 200; default 50

Responses

Status	Description
200	Paginated document list

24. POST /organizations/{organization}/documents

Summary: 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	In	Required	Type	Constraints
organization	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
project_id	no	string / null	—
title	yes	string	max length 500
caption	no	string / null	max length 2000
content_html	no	string / null	max length 1000000
status	no	string	one of: draft, published; default draft
editor_ids	no	array<string>	max items 100
tag_names	no	array<string>	max items 20

Responses

Status	Description
201	Document created
422	Validation failure

25. GET /documents/{document}

Summary: Read document

Requires documents:read.

Parameters

Name	In	Required	Type	Constraints
document	path	yes	string	—

Responses

Status	Description
200	Document detail

26. PATCH /documents/{document}

Summary: Update document

Requires documents:write. Can update publication state, archive state, project scope, content, and editor membership.

Parameters

Name	In	Required	Type	Constraints
document	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
project_id	no	string / null	—
title	no	string	max length 500
caption	no	string / null	max length 2000
content_html	no	string / null	max length 1000000
status	no	string	one of: draft, published
archived	no	boolean	—
editor_ids	no	array<string>	max items 100
tag_names	no	array<string>	max items 20

Responses

Status	Description
200	Document updated
422	Validation failure

27. DELETE /documents/{document}

Summary: Soft-delete document

Requires documents:write.

Parameters

Name	In	Required	Type	Constraints
document	path	yes	string	—

Responses

Status	Description
204	Document soft-deleted

28. POST /documents/{document}/comments

Summary: Create document comment

Requires document_comments:write.

Parameters

Name	In	Required	Type	Constraints
document	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
body_html	yes	string	max length 200000

Responses

Status	Description
201	Comment created
422	Validation failure

29. POST /organizations/{organization}/notifications

Summary: Send organization notifications

Requires notifications:write. Recipients must belong to the credential organization.

Parameters

Name	In	Required	Type	Constraints
organization	path	yes	string	—

JSON request body

Field	Required	Type	Constraints
user_ids	yes	array<string>	min items 1; max items 100
title	yes	string	max length 180
body	yes	string	max length 2000
url	no	string / null	—

Responses

Status	Description
201	Notifications queued/sent
422	Invalid recipient or URL

30. GET /projects/{project}/tags

Summary: List used project tags

Requires projects:read. Returns tags currently assigned to at least one ticket.

Parameters

Name	In	Required	Type	Constraints
project	path	yes	string	—

Responses

Status	Description
200	Used project tags with ticket counts

Component schemas

These are the reusable schemas defined by the supplied OpenAPI document.

Error

Field	Required	Type	Constraints
message	no	string	—

Project

Field	Required	Type	Constraints
id	no	string	—
organization_id	no	string	—
name	no	string	—
key	no	string	—
description	no	string / null	—
archived_at	no	string / null	format date-time

Board

Field	Required	Type	Constraints
id	no	string	—
project_id	no	string	—
name	no	string	—
slug	no	string	—
position	no	integer	—
color	no	string / null	—
wip_limit	no	integer / null	—
is_done	no	boolean	—
is_hidden	no	boolean	—

Ticket

Field	Required	Type	Constraints
id	no	string	—
project_id	no	string	—
board_id	no	string	—
number	no	integer	—
title	no	string	—
description_html	no	string / null	—
priority	no	string	one of: lowest, low, normal, high, highest, critical
position	no	integer	—
due_at	no	string / null	format date-time
started_at	no	string / null	format date-time
completed_at	no	string / null	format date-time
api_credential_id	no	string / null	—
archived_at	no	string / null	format date-time

Document

Field	Required	Type	Constraints
id	no	string	—
organization_id	no	string	—
project_id	no	string / null	—
author_id	no	string / null	—
title	no	string	—
caption	no	string / null	—
content_html	no	string / null	—
status	no	string	one of: draft, published
api_credential_id	no	string / null	—
published_at	no	string / null	format date-time
archived_at	no	string / null	format date-time
tags	no	array<object>	—
created_at	no	string	format date-time
updated_at	no	string	format date-time