Conventions

The production origin is https://platform.trycombined.com. Public REST operations are versioned below /v1. Send and accept application/json; request bodies are capped at 64 KiB at the public boundary, with some narrower handlers applying a smaller limit.

Success envelopes

Ordinary responses wrap the operation payload and a correlation ID:

{
  "data": { "runId": "00000000-0000-4000-8000-000000000020", "state": "queued" },
  "correlationId": "cor_01K2A000000000000000000101"
}

Paginated list responses use:

{
  "data": [],
  "page": { "nextCursor": null, "hasMore": false },
  "correlationId": "cor_01K2A000000000000000000101"
}

nextCursor is opaque, can be up to 1,024 characters, and is valid only for the same operation and filters. Continue until it is null; restart at the first page after filters change. Public paginated REST lists accept limit from 1 to 200 and default to 50 unless an endpoint schema says otherwise.

Correlation and caching

Every JSON envelope includes correlationId, and the same value is returned as X-Correlation-ID. Preserve it when reporting an error or reconciling an operation. API responses use Cache-Control: no-store; do not put authenticated responses in a shared cache.

Idempotency

Control-plane mutations require:

Idempotency-Key: 9f57c24e-5126-4bd5-8a5c-76f20b10e31d

Keys must contain 8–200 safe characters. Repeating the same operation, principal, key, and body returns the stored safe result when complete. Reusing a key with a different body or operation returns 409; an operation still in progress can also return 409.

POST /v1/sql accepts an optional idempotency key for recovery from an ambiguous transport failure. SDKs generate keys for non-GET calls. If the client did not receive a response, retry only with the original key and identical body; never generate a new key for the same intended mutation.

Dates, identifiers, and parameters

Resource identifiers are UUIDs. Date-time values use ISO 8601 with an explicit offset. SQL uses positional ? placeholders and a parameters array. Query parameters, path parameters, and JSON property names are case-sensitive.

Retry policy

Never retry validation, authorization, or not-found errors automatically. A GET can be retried after 429, 502, 503, or 504 with bounded backoff. Honor Retry-After when supplied. Mutation and SQL retry decisions require the original idempotency key and body. The official SDKs retry eligible GETs once and do not automatically retry SQL or mutations.

Asynchronous operations

Source authorization, manual runs, and Source deletion can return 202 with a request, run, or deletion job identifier. Acceptance means work was queued, not completed. Poll or inspect the corresponding Source/authorization status and Activity instead of assuming success.