API conventions and authentication

Base URL

Send public requests to the Node API, normally port 3000 in local development. Runtime Host is a private execution plane, not a second public API.

Bearer authentication

When the deployment enables API-token authentication, send:

Authorization: Bearer <token>

GRID_API_TOKEN protects ordinary /api/* routes. Liveness, readiness, metrics, the compatibility health route, public embed routes, and authentication entry points have separate public or scoped behavior.

Admin credentials and connector-ingress credentials are separate authorities. Never substitute a public API token for an admin token, or expose the private Node-to-Runtime-Host credential to a client.

JSON requests and responses

Use Content-Type: application/json for JSON request bodies. Public examples in these guides use JSON responses even where a route also supports another transport representation.

Errors

Treat the HTTP status as authoritative. Current routes do not share one universal error envelope. Depending on the route, explanatory text can appear in error or message, with an optional machine-readable code. Preserve the complete response for diagnostics instead of decoding every failure through one rigid client type.

Backpressure and retries

Honor Retry-After on 429 and 503. A Runtime Host admission failure can include:

{
  "ok": false,
  "code": "RUNTIME_BUSY",
  "error": "runtime request shed under load"
}

Do not blindly retry a mutating request. Add jitter, limit attempts, and use an endpoint's concurrency or idempotency field where one exists.

Optimistic concurrency

• Source replacement accepts baseSourceHash.
• Input writes accept expectedRequestRev.
• Connector events accept idempotencyKey.

On a conflict, refetch the current source or symbol state and deliberately reconcile. The exact public status/code mapping for every conflict is not yet a stable documented contract.

Capability discovery

Use GET /api/capabilities to inspect the exact product build. It reports a schema version, product version, catalog digest, and availability states for functions, surfaces, artifacts, workflows, and interoperability.

API compatibility

Public routes currently do not carry a URL version such as /v1, and there is no separately published semantic API-versioning policy. These guides are release-pinned. Use capability discovery where behavior can depend on the build, and exercise a compatibility test before upgrading production clients.