API Reference

REST API Overview

View as Markdown

Base URL

https://api.chaser.sh

Interactive API documentation:

  • OpenAPI spec: https://api.chaser.sh/api-docs/openapi.json
  • Swagger UI: https://api.chaser.sh/swagger-ui

Authentication

All /v1/* routes require a bearer token:

1Authorization: Bearer sk_your_key_here

Accepted token types:

  • API keys (sk_...)
  • JWT access tokens (from OAuth login)

Account selection

Select the active account context with:

1X-Chaser-Account: <account_id_or_name>

Accepts: account ID, exact account name, or personal. If omitted, your personal account is used.

All resources (sessions, workspaces, jobs, webhooks, audit) are scoped to the active account.

Session endpoints

EndpointMethodDescription
/v1/sessionsPOSTCreate a session
/v1/sessionsGETList sessions
/v1/sessions/{id}GETGet session details
/v1/sessions/{id}DELETETerminate session
/v1/sessions/bulk-terminatePOSTTerminate multiple sessions
/v1/sessions/{id}/ptyGETWebSocket PTY upgrade
/v1/sessions/{id}/resizePOSTResize PTY

Session gateway

Access session services through:

  • Subdomain: https://<session_id>.chaser.sh/
  • Path: https://api.chaser.sh/s/<session_id>/

Execution endpoints

EndpointMethodDescription
/v1/execPOSTAuto-spawn sandbox and execute
/v1/sessions/{id}/execPOSTExecute in existing session
/v1/sessions/{id}/self-testPOSTRuntime diagnostics
/v1/sessions/{id}/commandsGETList background commands
/v1/sessions/{id}/commands/{cid}GETGet command status
/v1/sessions/{id}/commands/{cid}/streamGETStream output (SSE)
/v1/sessions/{id}/commands/{cid}/stdinPOSTSend stdin input
/v1/sessions/{id}/commands/{cid}/killPOSTSignal the process

File transfer endpoints

EndpointMethodDescription
/v1/sessions/{id}/uploadPOSTUpload file (multipart)
/v1/sessions/{id}/downloadGETDownload file

File transfer is sandbox-only, with a 16 MB per-file limit.

Workspace endpoints

EndpointMethodDescription
/v1/workspacesPOSTCreate workspace
/v1/workspacesGETList workspaces
/v1/workspaces/importPOSTImport from GitHub
/v1/workspaces/bulk-deletePOSTBulk delete
/v1/workspaces/{ws}DELETEDelete workspace
/v1/workspaces/{ws}/namePUTSet/clear name
/v1/workspaces/{ws}/templatePUTToggle template
/v1/workspaces/{ws}/snapshotsGETList snapshots
/v1/workspaces/{ws}/snapshotsPOSTCreate snapshot
/v1/workspaces/{ws}/snapshots/{name}/restorePOSTRestore snapshot
/v1/workspaces/{ws}/snapshots/{name}DELETEDelete snapshot

Job endpoints

EndpointMethodDescription
/v1/jobsPOSTCreate a job
/v1/jobsGETList jobs
/v1/jobs/kindsGETList available job kinds
/v1/jobs/{id}GETGet job details
/v1/jobs/{id}/cancelPOSTCancel job
/v1/jobs/{id}/retryPOSTRetry job

Account endpoints

EndpointMethodDescription
/v1/accountsGETList accounts
/v1/accounts/currentGETCurrent account details
/v1/accounts/organizationsPOSTCreate organization
/v1/accounts/current/membersGETList members
/v1/accounts/current/membersPOSTAdd member
/v1/accounts/current/members/{uid}PATCHUpdate member role
/v1/accounts/current/members/{uid}DELETERemove member
/v1/accounts/current/service-accountsGETList service accounts
/v1/accounts/current/service-accountsPOSTCreate service account
/v1/accounts/current/service-accounts/{said}DELETEDelete service account
/v1/accounts/current/service-accounts/{said}/keysGETList SA keys
/v1/accounts/current/service-accounts/{said}/keysPOSTCreate SA key
/v1/accounts/current/service-accounts/{said}/keys/{kid}DELETERevoke SA key

Key and SSH endpoints

EndpointMethodDescription
/v1/keysGETList API keys
/v1/keysPOSTCreate API key
/v1/keys/{id}DELETERevoke API key
/v1/ssh-keysGETList SSH keys
/v1/ssh-keysPOSTRegister SSH key
/v1/ssh-keys/{id}DELETEDelete SSH key

Webhook endpoints

EndpointMethodDescription
/v1/webhooksGETList webhooks
/v1/webhooksPOSTCreate webhook
/v1/webhooks/{id}DELETEDelete webhook
/v1/webhooks/deliveriesGETList deliveries
/v1/webhooks/deliveries/{did}GETGet delivery details
/v1/webhooks/deliveries/{did}/replayPOSTReplay delivery
/v1/webhooks/deliveries/{did}/discardPOSTDiscard delivery

Billing endpoints

EndpointMethodDescription
/v1/billing/summaryGETBilling summary for active account
/v1/billing/accountPOSTUpdate billing configuration
/v1/billing/checkoutPOSTCreate Stripe checkout session

Audit endpoints

EndpointMethodDescription
/v1/audit/eventsGETList audit events

MCP endpoint

EndpointMethodDescription
/v1/mcpPOSTMCP JSON-RPC (tools/list, tools/call)

Auth endpoints

EndpointMethodDescription
/auth/registerPOSTRegister with email/password
/auth/loginPOSTLogin with email/password
/auth/google/loginGETGoogle OAuth login
/auth/google/callbackGETGoogle OAuth callback
/auth/github/loginGETGitHub OAuth login
/auth/github/callbackGETGitHub OAuth callback
/auth/codex/login-urlGETCodex OAuth login URL
/auth/codex/callbackGET/POSTCodex OAuth callback
/auth/meGETCurrent user info

Assistant endpoints

EndpointMethodDescription
/v1/assistantsPOSTCreate assistant
/v1/assistantsGETList assistants
/v1/assistants/{id}GETGet assistant
/v1/assistants/{id}PATCHUpdate assistant
/v1/assistants/{id}/pausePOSTPause assistant
/v1/assistants/{id}/resumePOSTResume assistant
/v1/assistants/{id}/channelsPOSTAdd channel binding
/v1/assistants/{id}/channels/{bid}DELETERemove binding
/v1/assistants/credentialsPUTStore credential
/v1/assistants/resolve-credentialPOSTResolve credential
/v1/assistants/resolve-channelPOSTResolve channel
/v1/assistants/{id}/runtime-stateGETGet runtime state
/v1/assistants/{id}/runtime-statePUTUpdate runtime state
/v1/assistants/{id}/usage-eventsPOSTRecord usage event
/v1/assistants/{id}/usage-eventsGETList usage events
/v1/assistants/{id}/config-change-requestsPOSTPropose config change
/v1/assistants/{id}/config-change-requests/{rid}/approvePOSTApprove change
/v1/assistants/{id}/config-change-requests/{rid}/denyPOSTDeny change

Scoped API keys

API keys can be created with specific permission scopes:

sessions.read, sessions.write, workspaces.read, workspaces.write, exec.write, files.read, files.write, keys.read, keys.write, billing.read, billing.write, audit.read, webhooks.read, webhooks.write

Keys created without scopes have full access. Keys are bound to the account selected at creation time.

Rate limiting

Write-heavy endpoints return 429 Too Many Requests when rate limits are exceeded. Responses include:

  • Retry-After
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset
  • X-RateLimit-Scope (principal or account)

Rate-limited surfaces: session mutations, workspace mutations, exec, file transfer, jobs, MCP, and webhook mutations.