Okatana External API v1¶

This page is the route-by-route endpoint reference. Start with the HTTP API guide for credential handling, pagination, error strategy, and client examples. A live, executable Scalar reference is available at /docs/api when it is enabled by the deployment.

Base path:

/api/v1

Authentication:

Authorization: Bearer oka_<public-id>.<secret>

All credentials belong to one organization. A credential cannot access a resource from another organization even when it has * scope.

Scopes¶

Scope	Operations
`*`	Every external API operation
`organization:read`	Read organization
`projects:read`	List/read projects
`projects:write`	Create, update, archive, and delete projects
`boards:read`	List boards
`boards:write`	Create, update, reorder, and delete boards
`tickets:read`	List/read tickets
`tickets:write`	Create/update/move/delete tickets
`comments:write`	Add ticket comments
`analytics:read`	Read project analytics
`documents:read`	List/read documents
`documents:write`	Create/update/publish/archive/delete documents and editor access
`document_comments:write`	Add document comments
`notifications:write`	Send organization notifications

Errors¶

Common statuses:

401 missing, invalid, expired, or revoked API credential
403 credential belongs to another organization or lacks scope
404 resource does not exist
422 validation, relationship, or WIP-limit failure
429 rate limit reached

Laravel JSON validation responses include a message and field errors.

Read organization¶

GET /api/v1/organizations/{organization}

Scope: organization:read

List projects¶

GET /api/v1/organizations/{organization}/projects

Scope: projects:read

Create project¶

POST /api/v1/organizations/{organization}/projects
Content-Type: application/json

Scope: projects:write

{
  "name": "Platform",
  "key": "PLAT",
  "description": "Platform engineering work"
}

The API creates the default Open, Hold, In-progress, Pull Request, and Deployed boards.

Read project¶

GET /api/v1/projects/{project}

Scope: projects:read

Project members¶

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

Scope: projects:read

Returns explicit project users plus organization owners/admins that have implicit project access.

Project labels¶

GET /api/v1/projects/{project}/labels

Scope: projects:read

Use these identifiers when assigning labels to tickets.

Project tags¶

GET /api/v1/projects/{project}/tags

Scope: projects:read

Returns project tags that are currently used by at least one ticket, including ticket counts.

Update project¶

PATCH /api/v1/projects/{project}

Scope: projects:write

Supported fields: name, description, and archived.

Delete project¶

DELETE /api/v1/projects/{project}

Scope: projects:write. The operation is a soft delete.

List boards¶

GET /api/v1/projects/{project}/boards

Scope: boards:read

Create board¶

POST /api/v1/projects/{project}/boards

Scope: boards:write. Supports name, color, wip_limit, and is_done.

Update board¶

PATCH /api/v1/boards/{board}

Scope: boards:write. Supports name, color, wip_limit, is_done, and is_hidden.

Reorder boards¶

PUT /api/v1/projects/{project}/boards/reorder

Scope: boards:write. Send board_ids in the required order.

Delete board¶

DELETE /api/v1/boards/{board}

Scope: boards:write. If the board contains tickets, pass move_to_board_id.

List tickets¶

GET /api/v1/projects/{project}/tickets?board_id=...&q=deployment&per_page=50

Scope: tickets:read

Maximum per_page is 200.

Create ticket¶

POST /api/v1/projects/{project}/tickets
Content-Type: application/json

Scope: tickets:write

Select a board using 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.

{
  "board_slug": "open",
  "title": "Design deployment runbook",
  "description_html": "<p>Write the first version.</p>",
  "priority": "high",
  "due_at": "2026-09-01T09:00:00+08:00",
  "assignee_ids": [],
  "label_ids": []
}

Reorder tickets in a board¶

PUT /api/v1/projects/{project}/tickets/reorder

Scope: tickets:write. Send board_id and the ordered ticket_ids array.

Read ticket¶

GET /api/v1/tickets/{ticket}

Scope: tickets:read

Update ticket¶

PATCH /api/v1/tickets/{ticket}
Content-Type: application/json

Scope: tickets:write

{
  "title": "Design and review deployment runbook",
  "priority": "highest",
  "archived": false
}

Move ticket¶

POST /api/v1/tickets/{ticket}/move
Content-Type: application/json

Scope: tickets:write

{
  "board_id": "01...",
  "position": 2000
}

position is optional. Without it, Okatana appends the ticket to the destination board.

Delete ticket¶

DELETE /api/v1/tickets/{ticket}

Scope: tickets:write

This is a soft delete.

Add comment¶

POST /api/v1/tickets/{ticket}/comments
Content-Type: application/json

Scope: comments:write

{
  "body_html": "<p>Deployment validation is complete.</p>"
}

The API credential is recorded as the audit actor. The comment keeps an API-author snapshot because it does not impersonate a browser user.

Project analytics¶

GET /api/v1/projects/{project}/analytics

Scope: analytics:read

Response includes total, done, open, overdue, completion percentage, and counts by board.

Send organization notification¶

POST /api/v1/organizations/{organization}/notifications
Content-Type: application/json

Scope: notifications:write

{
  "user_ids": ["01..."],
  "title": "Deployment window changed",
  "body": "Production deployment starts at 18:00.",
  "url": "/app/projects/01..."
}

Recipients must belong to the credential organization. url, when supplied, must be an internal /app path.

Documents¶

Document API credentials are organization-scoped. A document may be organization-wide or linked to a project in the same organization.

List documents¶

GET /api/v1/organizations/{organization}/documents?q=runbook&project_id=01...&status=published&tags=runbook,production&per_page=50

Scope: documents:read

Create document¶

POST /api/v1/organizations/{organization}/documents
Content-Type: application/json

Scope: documents:write

{
  "project_id": "01...",
  "title": "Production runbook",
  "caption": "How to deploy the production service",
  "content_html": "<h2>Deployment</h2><p>...</p>",
  "status": "draft",
  "editor_ids": ["01..."],
  "tag_names": ["runbook", "production"]
}

project_id is optional. status is draft or published. Every editor must have access to the selected organization/project scope. tag_names accepts up to 20 organization-scoped article tags; tag names are matched case-insensitively and reused across documents in the same organization. The API credential is recorded as the document author and its name will appear in the UI instead of the user who provisioned it.

Read document¶

GET /api/v1/documents/{document}

Scope: documents:read

Update document¶

PATCH /api/v1/documents/{document}
Content-Type: application/json

Scope: documents:write

The update can change project_id, title, caption, content_html, status, archived, editor_ids, and tag_names. Moving a document to another organization is not supported.

Delete document¶

DELETE /api/v1/documents/{document}

Scope: documents:write. This is a soft delete.

Add document comment¶

POST /api/v1/documents/{document}/comments
Content-Type: application/json

Scope: document_comments:write

{
  "body_html": "<p>Reviewed and approved.</p>"
}

Document webhook events¶

Document integrations can subscribe to these existing organization webhook events:

document.created
document.updated
document.published
document.drafted
document.archived
document.unarchived
document.deleted
document.comment.created
document.comment.updated
document.comment.deleted