HTTP integration and conventions

The client and connector HTTP reference is generated from the implementation in this checkout. Download its OpenAPI 3.1 specification for clients and inspection. The live service exposes its own version at /api/v1/openapi.json; use that document when integrating with a different deployed checkout.

Start with worked HTTP workflows for exact discovery/submission JSON, authenticated CLI and curl requests, multipart files, guarded management updates and SSE reconnection. Use the endpoint pages to check the full schema and status contract for your selected operation.

Authentication and transport

User routes use Authorization: Bearer <user-token>; /connector/v1 routes use the separate connector bearer authority. OpenAPI and /api/v1/auth/config are public. Use the actual HTTPS API origin supplied by the service administrator. The static documentation website requires no credentials and sends no API requests on your behalf.

Endpoint pages lead with purpose, exact scopes, resource authority, guards, retained retry state, specific failures and next action. These fields come from the tested operation records, also exported as x-enumeray-contract in OpenAPI. Scoped tokens still require the relevant account/resource permissions. A connector token cannot substitute for a user token, and a user token cannot claim connector work. The permissions reference explains scopes and role boundaries.

Stable operations and guarded changes

Run submission and upload reservation require Idempotency-Key. Persist it with the full unchanged request before the first network write. After a lost reply, retry with that same key and request. A changed request under the old key is an idempotency conflict; generating a new key can create new work.

Management endpoints that use expected_generation require the generation from current inspection. Publication activation uses expected_current_publication_id, omitted/null for the first publication and set to the observed current ID for an update. A conflict means another change may have won; inspect before deciding a replacement request.

Context lifecycle transitions retain the exact request and receipt. After an interrupted reply, use the same account and repeat the transition with its unchanged body and original expected_generation to recover a committed receipt. A different stale request conflicts. Do not replace the guard with the latest generation merely to retry.

Compute-grant limit updates use a strict generation check. Send both limits and the observed grant expected_generation to PUT /api/v1/connectors/{connector_id}/grants/{grant_id}. A committed change advances generation, so an identical retry with the old generation returns 409. After a lost reply, inspect that grant and its connector audit history before deliberately sending another update. An unchanged request at the current generation succeeds without incrementing generation or recording another update event.

Editable author publications are not HTTP bodies. publication.json uses top-level model, identity, execution and schema fields; saved release initialization normalizes them into a machine registration request with an assigned candidate ID. Execution-context manifests retain their spec envelope. Use each endpoint’s schemas when constructing HTTP requests, and preserve the exact machine body/identity for retries.

Error and method behavior

Errors contain code, message and request_id; input validation errors may include bounded correction details. Every application response has a fresh server-generated x-request-id. Retain that identifier for operational diagnosis without collecting private input or credentials.

Unknown paths return 404. Unsupported methods return 405 with Allow. Where GET is supported, HEAD returns its response headers without a body. Body limits apply to consumed streams and can be narrower per route. Read the documented status/schema for each operation instead of relying on message text. Retry transport uncertainty using saved operation identity; do not blindly retry an authorization, validation or generation conflict.

Pagination and live logs

Collection endpoints expose bounded page sizes and opaque continuation cursors. Preserve cursors unchanged and within the same identity/resource/history scope. Log history includes next_cursor for another page and resume_cursor for future polling even when no entry is present.

The SSE logs endpoint accepts either Last-Event-ID or the query cursor, never both. A 410 history_cursor_expired response supplies X-History-Recovery-Cursor; display the omitted prefix when resuming. Streams recheck authority and can close on revocation, source unavailability or shutdown. Poll run inspection independently because stream closure is not a terminal scientific outcome.

Files and capability URLs

Upload, completion and artifact-content operations refer to exact storage versions, measured sizes and checksums. Temporary capability URLs belong to the storage origin: never forward API bearer credentials to them or persist them as artifact identity. Artifact content returns a checked 303 to an exact-version storage GET capability. Request it separately without API authorization headers, verify full size/SHA-256, and request fresh capabilities after expiry. Accepted dependencies pin versions rather than a mutable object key.

Exported operation IDs are unique across user, connector and archive methods. The website and independent client generation consume the same specification. Personal-token inventory defaults to 50 entries (maximum 100). GET /api/v1/connectors lists administered connectors; grant-only discovery uses GET /api/v1/compute-grants. Neither a grant nor connector administration confers scientific-data access.

Scientific run, log, event, provenance and referenced-artifact reads use the same user routes for submitters and current model owners/co-admins. Submitters retain history after model execution access is revoked. Administrative reads are audited and membership is current; standalone unrelated uploads remain private. Log streams recheck credential and membership before each buffered entry and idle poll.

This reference covers client and connector operations. Service administration is handled by Enumeray.