OpenAPI contract reference¶

Title: Okatana External API
Version: 1.0.0
Server path: /api/v1

This page is generated from the exact OpenAPI YAML bundled in resources/openapi.yaml. When the YAML does not define a response schema, this page does not invent one.

GET `/organizations/{organization}`¶

Summary: Read organization
Scope: organization:read

Requires organization:read.

Parameters¶

Name	In	Required	Type	Constraints / description
`organization`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
200	Organization	—
401	Invalid credential	`#/components/schemas/Error`
403	Wrong organization or scope	—

GET `/organizations/{organization}/projects`¶

Summary: List projects
Scope: projects:read

Requires projects:read.

Parameters¶

Name	In	Required	Type	Constraints / description
`organization`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
200	Project list	—

POST `/organizations/{organization}/projects`¶

Summary: Create project
Scope: projects:write

Requires projects:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`organization`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`name`	yes	`string`	maxLength=180
`key`	yes	`string`	maxLength=12
`description`	no	`string \| null`	maxLength=5000

Responses¶

Status	Description	Formal JSON schema
201	Project created	—
422	Validation failure	—

GET `/projects/{project}`¶

Summary: Read project
Scope: projects:read

Requires projects:read.

Parameters¶

Name	In	Required	Type	Constraints / description
`project`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
200	Project	inline schema

PATCH `/projects/{project}`¶

Summary: Update project
Scope: projects:write

Requires projects:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`project`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`name`	no	`string`	maxLength=180
`description`	no	`string \| null`	maxLength=5000
`archived`	no	`boolean`

Responses¶

Status	Description	Formal JSON schema
200	Updated project	—
422	Validation failure	—

DELETE `/projects/{project}`¶

Summary: Soft-delete project
Scope: projects:write

Requires projects:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`project`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
204	Deleted	—

GET `/projects/{project}/members`¶

Summary: List project members
Scope: projects:read

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

Parameters¶

Name	In	Required	Type	Constraints / description
`project`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
200	Member list	—

GET `/projects/{project}/labels`¶

Summary: List project labels
Scope: projects:read

Requires projects:read.

Parameters¶

Name	In	Required	Type	Constraints / description
`project`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
200	Label list	—

GET `/projects/{project}/boards`¶

Summary: List project boards
Scope: boards:read

Requires boards:read.

Parameters¶

Name	In	Required	Type	Constraints / description
`project`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
200	Board list	—

POST `/projects/{project}/boards`¶

Summary: Create project board
Scope: boards:write

Requires boards:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`project`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`name`	yes	`string`	maxLength=120
`color`	no	`string \| null`	maxLength=32
`wip_limit`	no	`integer \| null`	minimum=1
`is_done`	no	`boolean`

Responses¶

Status	Description	Formal JSON schema
201	Board created	—
422	Validation failure	—

PUT `/projects/{project}/boards/reorder`¶

Summary: Reorder project boards
Scope: boards:write

Requires boards:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`project`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`board_ids`	yes	`array<string>`

Responses¶

Status	Description	Formal JSON schema
200	Reordered board list	—
422	Invalid board list	—

PATCH `/boards/{board}`¶

Summary: Update board
Scope: boards:write

Requires boards:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`board`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`name`	no	`string`	maxLength=120
`color`	no	`string \| null`	maxLength=32
`wip_limit`	no	`integer \| null`	minimum=1
`is_done`	no	`boolean`
`is_hidden`	no	`boolean`

Responses¶

Status	Description	Formal JSON schema
200	Updated board	—

DELETE `/boards/{board}`¶

Summary: Soft-delete board
Scope: boards:write

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

Parameters¶

Name	In	Required	Type	Constraints / description
`board`	path	true	`string`

JSON request body¶

Request body required: false.

Field	Required	Type	Constraints
`move_to_board_id`	no	`string`

Responses¶

Status	Description	Formal JSON schema
204	Deleted	—
422	Invalid target or WIP limit exceeded	—

GET `/projects/{project}/tickets`¶

Summary: List project tickets
Scope: tickets:read

Requires tickets:read.

Parameters¶

Name	In	Required	Type	Constraints / description
`project`	path	true	`string`
`board_id`	query	false	`string`
`q`	query	false	`string`
`per_page`	query	false	`integer`	minimum=1; maximum=200; default=50

Responses¶

Status	Description	Formal JSON schema
200	Paginated ticket list	—

POST `/projects/{project}/tickets`¶

Summary: Create ticket
Scope: tickets:write

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 / description
`project`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`board_id`	no	`string`
`board_slug`	no	`string`
`title`	yes	`string`	maxLength=500
`description_html`	no	`string \| null`	maxLength=200000
`priority`	no	`string`	enum=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	Formal JSON schema
201	Ticket created	—
422	Validation, relation, or WIP-limit failure	—

PUT `/projects/{project}/tickets/reorder`¶

Summary: Reorder tickets inside a board
Scope: tickets:write

Requires tickets:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`project`	path	true	`string`

JSON request body¶

Request body required: true.

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

Responses¶

Status	Description	Formal JSON schema
204	Reordered	—
422	Invalid ticket list	—

GET `/projects/{project}/analytics`¶

Summary: Read project analytics
Scope: analytics:read

Requires analytics:read.

Parameters¶

Name	In	Required	Type	Constraints / description
`project`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
200	Project analytics	—

GET `/tickets/{ticket}`¶

Summary: Read ticket
Scope: tickets:read

Requires tickets:read.

Parameters¶

Name	In	Required	Type	Constraints / description
`ticket`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
200	Ticket detail	—

PATCH `/tickets/{ticket}`¶

Summary: Update ticket
Scope: tickets:write

Requires tickets:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`ticket`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`title`	no	`string`	maxLength=500
`description_html`	no	`string \| null`	maxLength=200000
`priority`	no	`string`	enum=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	Formal JSON schema
200	Updated ticket	—

DELETE `/tickets/{ticket}`¶

Summary: Soft-delete ticket
Scope: tickets:write

Requires tickets:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`ticket`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
204	Deleted	—

POST `/tickets/{ticket}/move`¶

Summary: Move a ticket to another board
Scope: tickets:write

Requires tickets:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`ticket`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`board_id`	yes	`string`
`position`	no	`integer`	minimum=0

Responses¶

Status	Description	Formal JSON schema
200	Moved ticket	—
422	Invalid board or WIP limit reached	—

POST `/tickets/{ticket}/comments`¶

Summary: Create ticket comment
Scope: comments:write

Requires comments:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`ticket`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`body_html`	yes	`string`	maxLength=200000

Responses¶

Status	Description	Formal JSON schema
201	Comment created	—

GET `/organizations/{organization}/documents`¶

Summary: List organization documents
Scope: documents:read

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

Parameters¶

Name	In	Required	Type	Constraints / description
`organization`	path	true	`string`
`project_id`	query	false	`string`
`status`	query	false	`string`	enum=draft, published
`q`	query	false	`string`
`tags`	query	false	`string`	Comma-separated tag names. Multiple names use match-all filtering.
`per_page`	query	false	`integer`	minimum=1; maximum=200; default=50

Responses¶

Status	Description	Formal JSON schema
200	Paginated document list	—

POST `/organizations/{organization}/documents`¶

Summary: Create document
Scope: documents:write

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 / description
`organization`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`project_id`	no	`string \| null`
`title`	yes	`string`	maxLength=500
`caption`	no	`string \| null`	maxLength=2000
`content_html`	no	`string \| null`	maxLength=1000000
`status`	no	`string`	default=draft; enum=draft, published
`editor_ids`	no	`array<string>`	maxItems=100
`tag_names`	no	`array<string>`	maxItems=20; item maxLength=50

Responses¶

Status	Description	Formal JSON schema
201	Document created	inline schema
422	Validation failure	—

GET `/documents/{document}`¶

Summary: Read document
Scope: documents:read

Requires documents:read.

Parameters¶

Name	In	Required	Type	Constraints / description
`document`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
200	Document detail	inline schema

PATCH `/documents/{document}`¶

Summary: Update document
Scope: documents:write

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

Parameters¶

Name	In	Required	Type	Constraints / description
`document`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`project_id`	no	`string \| null`
`title`	no	`string`	maxLength=500
`caption`	no	`string \| null`	maxLength=2000
`content_html`	no	`string \| null`	maxLength=1000000
`status`	no	`string`	enum=draft, published
`archived`	no	`boolean`
`editor_ids`	no	`array<string>`	maxItems=100
`tag_names`	no	`array<string>`	maxItems=20; item maxLength=50

Responses¶

Status	Description	Formal JSON schema
200	Document updated	—
422	Validation failure	—

DELETE `/documents/{document}`¶

Summary: Soft-delete document
Scope: documents:write

Requires documents:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`document`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
204	Document soft-deleted	—

POST `/documents/{document}/comments`¶

Summary: Create document comment
Scope: document_comments:write

Requires document_comments:write.

Parameters¶

Name	In	Required	Type	Constraints / description
`document`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`body_html`	yes	`string`	maxLength=200000

Responses¶

Status	Description	Formal JSON schema
201	Comment created	—
422	Validation failure	—

POST `/organizations/{organization}/notifications`¶

Summary: Send organization notifications
Scope: notifications:write

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

Parameters¶

Name	In	Required	Type	Constraints / description
`organization`	path	true	`string`

JSON request body¶

Request body required: true.

Field	Required	Type	Constraints
`user_ids`	yes	`array<string>`	minItems=1; maxItems=100
`title`	yes	`string`	maxLength=180
`body`	yes	`string`	maxLength=2000
`url`	no	`string \| null`	Internal /app path only

Responses¶

Status	Description	Formal JSON schema
201	Notifications queued/sent	—
422	Invalid recipient or URL	—

GET `/projects/{project}/tags`¶

Summary: List used project tags
Scope: projects:read

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

Parameters¶

Name	In	Required	Type	Constraints / description
`project`	path	true	`string`

Responses¶

Status	Description	Formal JSON schema
200	Used project tags with ticket counts	—

OpenAPI contract reference¶

GET /organizations/{organization}¶

Parameters¶

Responses¶

GET /organizations/{organization}/projects¶

Parameters¶

Responses¶

POST /organizations/{organization}/projects¶

Parameters¶

JSON request body¶

Responses¶

GET /projects/{project}¶

Parameters¶

Responses¶

PATCH /projects/{project}¶

Parameters¶

JSON request body¶

Responses¶

DELETE /projects/{project}¶

Parameters¶

Responses¶

GET /projects/{project}/members¶

Parameters¶

Responses¶

GET /projects/{project}/labels¶

Parameters¶

Responses¶

GET /projects/{project}/boards¶

Parameters¶

Responses¶

POST /projects/{project}/boards¶

Parameters¶

JSON request body¶

Responses¶

PUT /projects/{project}/boards/reorder¶

Parameters¶

JSON request body¶

Responses¶

PATCH /boards/{board}¶

Parameters¶

JSON request body¶

Responses¶

DELETE /boards/{board}¶

Parameters¶

JSON request body¶

Responses¶

GET /projects/{project}/tickets¶

Parameters¶

Responses¶

POST /projects/{project}/tickets¶

Parameters¶

JSON request body¶

Responses¶

PUT /projects/{project}/tickets/reorder¶

Parameters¶

JSON request body¶

Responses¶

GET /projects/{project}/analytics¶

Parameters¶

Responses¶

GET /tickets/{ticket}¶

Parameters¶

Responses¶

PATCH /tickets/{ticket}¶

Parameters¶

JSON request body¶

Responses¶

DELETE /tickets/{ticket}¶

Parameters¶

Responses¶

POST /tickets/{ticket}/move¶

Parameters¶

JSON request body¶

Responses¶

POST /tickets/{ticket}/comments¶

Parameters¶

JSON request body¶

Responses¶

GET /organizations/{organization}/documents¶

Parameters¶

GET `/organizations/{organization}`¶

GET `/organizations/{organization}/projects`¶

POST `/organizations/{organization}/projects`¶

GET `/projects/{project}`¶

PATCH `/projects/{project}`¶

DELETE `/projects/{project}`¶

GET `/projects/{project}/members`¶

GET `/projects/{project}/labels`¶

GET `/projects/{project}/boards`¶

POST `/projects/{project}/boards`¶

PUT `/projects/{project}/boards/reorder`¶

PATCH `/boards/{board}`¶

DELETE `/boards/{board}`¶

GET `/projects/{project}/tickets`¶

POST `/projects/{project}/tickets`¶

PUT `/projects/{project}/tickets/reorder`¶

GET `/projects/{project}/analytics`¶

GET `/tickets/{ticket}`¶

PATCH `/tickets/{ticket}`¶

DELETE `/tickets/{ticket}`¶

POST `/tickets/{ticket}/move`¶

POST `/tickets/{ticket}/comments`¶

GET `/organizations/{organization}/documents`¶

POST `/organizations/{organization}/documents`¶

GET `/documents/{document}`¶

PATCH `/documents/{document}`¶

DELETE `/documents/{document}`¶

POST `/documents/{document}/comments`¶

POST `/organizations/{organization}/notifications`¶

GET `/projects/{project}/tags`¶