API / V1

Drive GoClaw through a stable HTTP contract.

The production API base URL is https://goclawai.com/api/v1. Examples use a workspace-scoped short-lived Bearer token; browser sessions additionally require CSRF protection.

BASE URL

Verify version and identity first

The version endpoint is public. Other requests use Authorization: Bearer; a token-bound workspace makes the workspace header optional, but sending it explicitly catches configuration mistakes.

Check the production API

curl -fsS https://goclawai.com/api/v1/version

curl -fsS https://goclawai.com/api/v1/workspaces/current \
  -H "Authorization: Bearer ${GOCLAW_TOKEN}" \
  -H "X-GoClaw-Workspace-ID: ${GOCLAW_WORKSPACE}"

CREATE RUN

Create a Run idempotently

POST /runs accepts workload, provider, and region. Reuse the same Idempotency-Key for retries of one logical request; do not generate a new key after every network failure.

Submit a minimal Run

curl -fsS https://goclawai.com/api/v1/runs \
  -X POST \
  -H "Authorization: Bearer ${GOCLAW_TOKEN}" \
  -H "X-GoClaw-Workspace-ID: ${GOCLAW_WORKSPACE}" \
  -H "Idempotency-Key: onboarding-run-001" \
  -H "Content-Type: application/json" \
  --data '{"workload":{"image":"alpine"},"provider":"auto","region":"auto"}'

OBSERVE

Poll state or resume the event stream

GET /runs/{runId} returns the current derived state. GET /runs/{runId}/events uses text/event-stream; reconnect with the final event ID in Last-Event-ID.

GET /api/v1/runs/{runId}
GET /api/v1/runs/{runId}/events
POST /api/v1/runs/{runId}:cancel

ERRORS

Handle errors as Problem Details

Errors use application/problem+json with a stable code, requestId, retryable flag, and optional params. Branch on code and HTTP status, never on the human title.

409 can represent approval, version, or idempotency conflicts.
Use bounded backoff for 429 and retryable 5xx responses.
Retain X-Request-ID for support, but never attach the token.

CONTRACT

OpenAPI is the machine contract

The OpenAPI 3.0 document defines fields, enums, headers, response codes, and schemas. Pin a version when generating clients and review contract changes before upgrades.

View OpenAPI

SECURITY

Never use a provider key as an API token

GOCLAW_TOKEN authorizes a GoClaw workspace; provider keys such as Bailian belong only in Provider Credentials. Neither should appear in URLs, logs, screenshots, or frontend source.