REST API

Call the Kortix API directly: base URL, authentication, errors, retries, and where the full route reference lives.

The Kortix REST API is the HTTP interface to accounts, projects, sessions, secrets, connectors, triggers, and Apps. The web app, the CLI, the SDK, and the Kortix MCP server all call it. Use it directly from any language that can send an HTTPS request with a bearer token.

The shortest path: create a personal access key, list your projects, and start a session.

kortix tokens new my-script --expires 30d    # prints kortix_pat_… once
export TOKEN=kortix_pat_...

curl -s https://api.kortix.com/v1/projects \
  -H "Authorization: Bearer $TOKEN"

curl -s https://api.kortix.com/v1/projects/<project_id>/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"initial_prompt": "Summarize the open change requests."}'

GET /v1/projects returns an array of projects, each with project_id. The session create returns 201 with the session, including session_id and branch_name. It returns 202 with status, command_id, and session_id when Kortix queues the create. Read the session with GET /v1/projects/<project_id>/sessions/<session_id> until it appears.

Pick a surface

All four surfaces reach the same API with the same permissions.

Prefer the SDK for anything that drives a session: it owns the start, the readiness wait, the event stream, and the runtime routes that the REST reference does not list.

Base URL and reference

Every deployment serves its own route reference:

• GET /v1/docs: the interactive reference. The API reference tab at the top of these docs opens the Kortix Cloud copy.
• GET /v1/openapi.json: the OpenAPI 3.1 document. Its servers entry is the origin you requested it from, so a client generated from a self-hosted instance points at that instance.
• GET /v1/health: no token needed. Returns status, version, and commit.

The reference leaves out operator routes. A self-host operator turns off both /v1/docs and /v1/openapi.json with OPENAPI_PUBLIC_DOCS=false in the API environment.

Authenticate

Send one header on every request:

Authorization: Bearer <token>

The token decides who the request acts as. Every Kortix credential starts with a prefix that names its kind. Create and manage them on Sign-in, SSO & API keys.

An OAuth token without the kortix scope reaches only /v1/accounts/me, /v1/oauth/userinfo, and /v1/oauth/revoke. Other routes answer 403, and message starts with insufficient_scope.

A person’s access token from headless sign-in also works as a bearer token. It acts as that person.

A missing or invalid token returns 401. A 401 with code: "session_token_revoked" means the credential is revoked, expired, or belongs to a closed session. It never works again: stop retrying and get a new token.

The same tokens open the project’s git origin. See Git.

Errors

An error response is JSON. Every body has error. The generic shape adds message and status. A typed error adds code and can add more fields.

Some errors add fields. A failed body, query, or path validation returns:

{ "error": true, "message": "Validation failed", "status": 400, "issues": [ … ] }

issues lists each invalid field with its path and message.

Every response carries an X-Request-Id header. Quote it when you report a problem.

Common error codes

These are the codes clients branch on most. The linked page explains each fix.

A connector call reports its outcome in reason, not code, inside { ok: false, status: "denied" | "error", reason }. The reasons, such as connector_not_connected and policy_block, are on Connectors. LLM provider and model failures are on Models.

Retries and idempotency

The SDK retries reads, and a DELETE that got no response. It never repeats any other write. In your own client, decide per response:

Idempotency-Key

Two create routes deduplicate a retried request:

Send a new random value, such as a UUID, for each intent. Send the same value again when you retry that intent. A repeated session create returns the original session instead of starting a second sandbox. Session keys are unique across all of Kortix. A key that another project or account already used returns 409 IDEMPOTENCY_KEY_CONFLICT.

Pagination

A list route that pages takes limit and cursor. Pass the next cursor back as cursor. No next cursor means you have the last page.

The session list also returns an ETag. Send it back as If-None-Match and an unchanged list answers 304 with no body.

Rate limits

A rate-limited route returns X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (seconds until the window resets). When the limit is reached it returns 429 with Retry-After and this body:

{ "error": "rate_limit_exceeded", "message": "Rate limit exceeded. Please retry shortly.", "retry_after_seconds": 12 }

What the reference does not cover

The reference does not list the session runtime routes. The surfaces below also take a different credential or protocol than a plain bearer call:

Machine-readable docs

These docs are also published as plain Markdown for coding agents and LLM tools:

Point a coding agent at https://kortix.com/llms.txt for the concepts and at https://api.kortix.com/v1/openapi.json for the exact routes. An MCP client that uses the Kortix MCP server reads the route reference itself through search_api and describe_api.