External API

The external API uses /api/v1 resource paths with service-account Bearer tokens. Create tokens from Settings -> API keys.

API keys are built for CI systems, internal tools, and coding agents. Each key belongs to a durable integration identity. Each secret token under that integration is disposable and shown only once.

Authentication

Send the token in Authorization:

curl https://your-143.example.com/api/v1/sessions \
  -H "Authorization: Bearer 143_live_..." \
  -H "143-Version: 2026-06-01"

Recommended headers:

Disabled integrations, revoked tokens, expired tokens, missing scopes, and source IPs outside a token allowlist cannot authenticate.

Creating Keys

Admins create keys in Settings -> API keys:

1. Name the integration, for example Cursor, GitHub Actions, or Deploy bot.
2. Choose Full external API access or Custom access.
3. Optionally restrict repositories.
4. Choose an expiration.
5. Optionally restrict source IP addresses or CIDR ranges.
6. Copy the one-time token into a secret manager.

The token value is never shown again. Rotate by creating a replacement token under the same integration, deploying it, and revoking the old token.

Scopes

Use the narrowest scope set that lets the caller do its job.

There is no global wildcard scope. The dashboard's Full external API access preset expands to explicit operation scopes.

Repository Restrictions

Tokens can be limited to repository IDs. An empty repository list means all repositories in the organization. When a request names or resolves a repository, the token must be allowed for that repository.

Source IP Restrictions

Tokens can be limited to source IPs or CIDR ranges:

203.0.113.10/32
198.51.100.7
2001:db8::/32

An empty IP allowlist means any source IP is accepted.

Idempotency

Send Idempotency-Key on retried POST requests. Keys are scoped to the API client, method, and path, and retained for 24 hours.

Idempotent POST routes:

Example:

curl https://your-143.example.com/api/v1/sessions \
  -X POST \
  -H "Authorization: Bearer 143_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-2026-06-01-001" \
  -d '{
    "message": "Fix the failing deployment check",
    "repository_id": "00000000-0000-0000-0000-000000000000",
    "metadata": {"caller": "deploy-bot", "deployment_id": "dep_123"}
  }'

Reusing a key with different request content returns 409 IDEMPOTENCY_KEY_REUSED.

Rate Limits

Rate limits are per token:

Responses include:

Errors

Errors use the standard API envelope:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API token is missing required scope",
    "details": {
      "required_scope": "sessions:create"
    }
  }
}

Common external API errors:

Endpoint Coverage

Only routes in this table accept external API tokens. Other protected app/admin routes return 403 FORBIDDEN.

Sessions

Create a session:

{
  "message": "Investigate the checkout error",
  "repository_id": "00000000-0000-0000-0000-000000000000",
  "target_branch": "main",
  "agent_type": "codex",
  "metadata": {
    "caller": "support-workflow",
    "ticket_id": "SUP-123"
  }
}

Required scope: sessions:create or sessions:all.

Automations

Create an automation:

{
  "name": "Nightly dependency review",
  "goal": "Review dependency updates and open pull requests for safe upgrades.",
  "repository_id": "00000000-0000-0000-0000-000000000000",
  "schedule": {
    "type": "cron",
    "cron": "0 2 * * *",
    "timezone": "UTC"
  },
  "identity": {"scope": "org"},
  "metadata": {
    "caller": "platform",
    "workflow_id": "deps-nightly"
  }
}

Required scope: automations:create or automations:all. External API automations must use identity.scope=org.

Previews

Create a preview:

{
  "repository_id": "00000000-0000-0000-0000-000000000000",
  "branch": "main",
  "source": {
    "type": "automation",
    "external_id": "nightly-preview"
  }
}

Required scope: previews:create or previews:all.

Coding Agents

For coding agents and automation runners:

• Store the token in the platform secret manager, not in prompts or repository files.
• Send Idempotency-Key for every retried POST.
• Set metadata.caller and a stable workflow or run identifier on create requests.
• Prefer family scopes such as sessions:all for agents that operate within one product area.
• Prefer repository restrictions for single-repository agents.
• Use 143-Version so logs identify the client behavior during debugging.

Schema And OpenAPI

The canonical schema is the route behavior documented here and the JSON examples above. If generated OpenAPI output is unavailable in your deployment, coding agents should use this page, /llms.txt, and the raw docs route at /api/docs/raw/reference/external-api as the source of truth.