HTTP API schema¶

The daemon exposes an HTTP API (used by the CLI, TUI, and remote clients). Its shape is published as an OpenAPI 3.1 document so out-of-process clients can generate typed clients instead of hand-copying wire structs.

Getting the schema¶

The schema is committed at api/openapi.yaml and regenerated by the kata binary:

kata openapi > openapi.yaml

kata openapi builds the document in-process from the daemon's route definitions, so it needs neither a running daemon nor a database. The runtime /openapi.json route stays disabled; the committed artifact and this command are the supported way to obtain the schema.

What the schema is¶

A per-release snapshot of the daemon's current HTTP API — a faithful description of the routes and wire types as they exist at that commit. It is useful for client generation and review.

It is not a promise of a forever-stable API. Treat it as the contract for the daemon version you generated it against, not a guarantee that a future daemon will accept the same calls.

Detecting the API version¶

The schema carries a version in its info.version field (APISchemaVersion). The same value is reported at runtime by GET /api/v1/health as api_schema_version:

{
  "ok": true,
  "schema_version": 7,
  "api_schema_version": "0.6.0",
  "version": "1.4.2",
  "uptime": "5m0s",
  "db_path": "/path/to/kata.db"
}

Three distinct version fields appear here; they answer different questions:

A client can read api_schema_version once at startup and decide whether it recognizes the daemon's API before issuing further calls. Compare it for equality against the info.version of the schema the client was generated from: the value is semver-shaped, but no ordering semantics are defined, so treat any other value as "verify compatibility" rather than inferring safety from an unchanged major or minor component.

The field is optional in the schema even though current daemons always send it. That is deliberate: a version-detection field has to survive version skew, so a client generated from a schema that includes it can still parse the response of an older daemon that predates it. Treat an absent or empty api_schema_version as "a daemon older than this field," not a parse error.

Version history¶

Compatibility expectations¶

These are the current intentions, not a contractual guarantee:

• Additive changes are not signalled. New endpoints, and new optional response fields, can appear without an api_schema_version change. Response objects are published with additionalProperties: true, so a client generated from the schema tolerates fields it does not yet know about even under strict validation. The response relaxation never loosens request schemas: those keep the strictness their types declare — additionalProperties: false by default, so unknown request fields are rejected unless a type explicitly opts in. New optional request fields and query parameters do bump api_schema_version: generated clients may emit them, and older strict daemons may reject them. The OpenAPI 3.0 flavor (kata openapi --version 3.0), which exists as code-generator input, leaves additionalProperties unset on response schemas instead — the same permissive meaning, phrased so generators model optional object-valued response fields (such as parent) as pointers rather than always-present values.
• Breaking changes bump api_schema_version. Removing or renaming a field, changing a field's type, or removing an endpoint is a breaking change and is signalled by a change to api_schema_version. A client that pins or checks the value it was generated against can detect the mismatch instead of failing at an arbitrary call site.
• Regeneration stays honest. A committed golden test fails if api/openapi.yaml drifts from the routes, so the published schema cannot silently fall out of date with the daemon it describes.

If you build against this schema and hit a gap, please open an issue — the contract is meant to be useful to external clients, and feedback shapes how far the compatibility guarantees are taken.

Comment Endpoints¶

Comments can be appended with POST /api/v1/projects/{project_id}/issues/{ref}/comments and edited in place with PATCH /api/v1/projects/{project_id}/issues/{ref}/comments/{comment_ref}. Use the comment UID as comment_ref; numeric comment IDs are local storage artifacts.

Editing a comment overwrites the current comment body while preserving the original author, UID, creation time, and thread position. This is the supported primitive for redacting comment text before enrolling a project in federation. It is not a purge mechanism for data that has already crossed into another federated event log.

Project Hygiene Endpoints¶

POST /api/v1/projects/{project_id}/actions/rewrite-author rewrites one exact author identity in the project's current rows. The request body carries actor, from, and to; to must be non-empty. The daemon updates issue authors, issue owners, comment authors, and link authors that exactly match from, emits one project.author_rewritten event when anything changed, and returns per-field counts. The endpoint refuses already-federated projects because it is a current-state hygiene operation for local project rows, not a federated history rewrite.

Issue Graph Endpoint¶

GET /api/v1/projects/{project_id}/issues/{ref}/graph returns the relationship graph reachable from one source issue. The path ref accepts the same issue ref forms as other project-scoped issue endpoints. The optional depth query value is either full (the default) or a non-negative hop count such as 1, 2, or 3. Pass hide_done=true to keep the source issue but exclude closed non-source issues from traversal and output.

The response body is a canonical graph payload:

Edge direction is normalized for clients: parent edges point parent -> child, blocks edges point blocker -> blocked, and related edges use kata's canonical related-link ordering. layout=false keeps an edge in the graph while telling layout engines they can omit it from force/layout calculations; current daemons use that hint for transitive blocks edges.

Soft-deleted issues and issues in archived projects are hidden instead of reported as unresolved references. unresolved_refs is reserved for dangling endpoints that can appear after imports, federation repair, or manual database maintenance, so graph clients can surface incomplete data without discarding the reachable graph.

Issue Sync Endpoints¶

Issue sync endpoints are project-scoped and provider-qualified. They configure one-way external issue sync into the kata project. GitHub is the only provider implemented in v1, and these endpoints back the kata sync github ... commands.

All GitHub access happens in the daemon process. For provider github, v1 accepts github.com and exact GitHub Enterprise hostnames listed in KATA_GITHUB_SYNC_ALLOWED_HOSTS. The daemon resolves credentials in this order: a matching [[github_sync.app]] entry, the explicit token env named by [github_sync].token_env (default KATA_GITHUB_TOKEN) only when [github_sync].token_host matches the binding host, then gh auth token --hostname <host> as a local fallback. Remote clients call these endpoints on the daemon, so client-side GitHub credentials are not sufficient when the daemon runs elsewhere, for example behind https://daemon.example.

The GitHub App credential path is the recommended shared-daemon deployment model. The App only needs Metadata read and Issues read permissions. The gh auth token fallback is best suited to local and single-user daemons. GitHub-sourced parent links are imported when the host exposes the queried parent fields; unsupported schemas are nonfatal and preserve existing source-managed parent links.

The API surface is provider-neutral so future providers such as GitLab or Linear can use the same lifecycle endpoints. Provider-specific identity lives inside the config object, which must not contain raw credentials; providers that need credentials should use a credential reference or a daemon-local auth mechanism.

JSONL restore imports issue sync bindings as disabled. Re-enable them locally after verifying the restored host and daemon credentials.

Enable sync:

POST /api/v1/projects/{project_id}/issue-sync/github/enable
Content-Type: application/json

{
  "config": {
    "host": "github.com",
    "owner": "example-org",
    "repo": "example-repo",
    "title_prefix": true
  },
  "interval": "5m"
}

For GitHub, config.host defaults to github.com. Clients may send interval_seconds instead of interval. config.title_prefix defaults to true; set it to false to preserve GitHub issue titles without the [GitHub #123] prefix. The daemon validates the repository with its configured GitHub credential chain, stores the repository identity, and returns the binding and status.

Disable sync:

POST /api/v1/projects/{project_id}/issue-sync/github/disable
Content-Type: application/json

{}

Disabling stops polling but keeps the binding, cursor, status, and import mappings so re-enabling can resume against the same repository identity.

Read status:

GET /api/v1/projects/{project_id}/issue-sync/github/status

Status returns a not_enabled state when the project has no binding. Existing disabled bindings are returned with their last run status.

Run once:

POST /api/v1/projects/{project_id}/issue-sync/github/once
Content-Type: application/json

{}

once runs one immediate daemon-side sync for an enabled binding. It bypasses the interval schedule but still respects the in-flight guard; overlapping runs return a conflict.

The shared response body contains:

Synced issues are GitHub-owned for title, body, state, labels, owner, and imported GitHub comments. API clients should treat those fields as read-mostly in kata: kata does not write back to GitHub, and newer GitHub updates can overwrite local issue or comment edits to those fields.

V1 does not support GitHub write-back, timeline events, pull requests, deleted or transferred issue propagation, edited or deleted comment propagation, or multiple assignees beyond the first GitHub assignee.