/v1 at your control-plane origin. For a default local installation this is http://127.0.0.1:8787/v1. Use the configured HTTPS origin for hosted deployments. /v1 is the route prefix, not proof that every development snapshot has an identical schema. Record the server build and read upgrade notes.
Find an operation
Every literal management route in the current server has a draft operation-page assignment. The mapping checks route/page presence, not exhaustive schema accuracy or runtime acceptance. Use the contracts below for request/response behavior and the generated inventory for route permissions.Authentication and common conventions
Trusted backend clients sendAuthorization: Bearer <token>. Local Console can use its separate workspace bootstrap. API identities resolve a tenant and role; every resource lookup/binding must remain tenant-scoped. Application tokens have an explicit route allowlist. A valid application token does not authorize approval decisions, account credential administration or arbitrary deployment changes. Missing/invalid identity returns 401; an application token on an owner route returns 403 owner_token_required.
Use Content-Type: application/json for JSON bodies. Parameter identifiers must satisfy the route schema, often UUID; URL-encode path values. Unknown fields are rejected where the schema is strict. Responses are JSON except artifact content, SSE and empty 204 responses. Do not assume every DELETE returns 204 or every creation returns 201: Run submission returns 202. See errors and limits.
The following read-only request requires a real backend token already present in the environment. It does not create resources:
HEXAGON_API_URL here is an example variable read by the shell, not a server bootstrap setting.
Management route inventory
This table is generated from literalapi.get/post/put/patch/delete registrations in server.ts. Application-token classification calls the actual policy. Route presence is conditional on services supplied at startup; local deployment settings routes are not promised on hosted deployments. “Allowed” is the role check, not a waiver of ownership, state, capability or body validation.
Regenerate with
npx tsx tooling/generate-http-doc-index.ts. No server, provider or model request is made by the generator. Operation-specific schemas, effects and curl workflows live in the linked reference pages. Provider-specific config details and executable end-to-end examples still require their own review. The generator also writes the route coverage ledger; assignment is not completion.
Resource contracts and effects
Exact field restrictions and examples are in configuration, Python, TypeScript, connection lifecycle, OCI, approvals and reconciliation. These links supplement the operation-specific contracts; use each contract for exact fields, errors, side effects and request examples.
Idempotency, pagination and observation
For Run submission, persist the exact Session, input, origin and key before sending. The same request/key recovers the original Run; changed content conflicts. Session creation and other arbitrary POST operations do not inherit that guarantee. A transport timeout can follow a successful remote side effect. Investigate the original object/operation before repeating it. Session and Run collection routes accept their implemented query filters; resource operations use limit/offset. A Session’s Run list uses abefore timestamp and a bounded page, rather than the global list’s offset contract. Event queries use numeric-string after cursors with at most 500 entries. Do not apply one pagination strategy to every endpoint.
SSE /runs/:id/stream accepts after or Last-Event-ID, with explicit after taking precedence. Events are persisted first. Deduplicate and commit events/cursor together; stream.end is an unnumbered transport marker. Query the Run afterward. Disconnecting does not cancel execution. See events and states.
Other HTTP surfaces
GET /health/live is a non-authenticated liveness probe, not readiness. /local/connect is a conditional local bootstrap with its own protections, not hosted login. OAuth callbacks, preview grants and credential-access traffic have separate handlers and authentication; they are not anonymous alternatives to /v1 management routes. Runtime endpoints inside the Sandbox are internal execution protocol and must not be used with owner tokens.
This reference does not advertise a nonexistent OpenAPI download or a generic deployment API. The linked operation pages describe schemas, errors, effects and examples, reviewed against implementation in the first closeout batch. The generated inventory itself proves route assignment only; HTTP execution and cloud acceptance require their separately scoped evidence.