Create run
Accept one durable scientific execution intent.
Credential scopes: runs:create
Resource authority: Authorized model user; candidate trials additionally require models:manage and current model-administrator/captured-grant or named-delegation authority.
Retry: Persist the request and Idempotency-Key before sending; repeat both unchanged after a lost reply. The same account/key returns the original acceptance receipt, not current run status.
Guards: Explicit expected_publication_id, current access/admission and compatible declared inputs. Keys identify semantic requests and belong to the user, not one credential.
Retain: API/account, full original body, Idempotency-Key and returned run/receipt identities.
Specific failures: 409 idempotency_conflict; 413 payload_too_large; 422 invalid_inputs or invalid_artifact_input; 429 queue capacity
Next action: Inspect the recovered run; a deliberate new execution requires a new key. Worked workflow
Run creation requires model_id, expected_publication_id, inputs. Successful retries return their original receipt even after publication/access changes. New work with a stale publication returns 409 publication_changed.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Required once. Scoped to this user and run creation; retain the same key and semantic request after a lost response. Successful keys do not expire.
Request Bodyrequired
Section titled “Request Bodyrequired”Exact publication and fully specified inputs. Omitted purpose means standard and requires the current publication with public admission open. candidate_trial requires runs:create plus models:manage, current model administration/execution access and ownership of the captured compute grant or an exact active publication_delegation_id; it permits ready or published retained candidates without altering public admission. Fresh trials reject retirement, revocation, unavailable installations and maintenance. Trial intent persists through activation; execution success is advisory. JSON supports declared stored-artifact references. Multipart contains one application/json request part with this envelope, and at most 8 uniquely named attachment parts with explicit parameter-free media types. Only declared file inputs recognize closed {attachment: part-name} references; all attachments must be used. Parts may occur in any order; filenames are ignored. Total bytes obey ENUMERAY_MAX_REQUEST_BODY_BYTES (default 1 MiB, maximum 16 MiB), JSON part at most 1 MiB and inputs at most 64 KiB. Body deadline 60 seconds, staging deadline 120 seconds, four concurrent multipart submissions per process. Unknown/duplicate envelope fields and query parameters are rejected. JSON suffix media types (application/*+json) are also supported.
Fully specified inputs for one exact publication; ownership comes from authentication.
object
Exact publication: current-publication precondition for standard runs, explicit candidate for trials.
Required JSON value, including null when allowed by the publication schema. JSON Schema default annotations do not populate omitted inputs.
Stable catalog model identity.
Immutable submission intent. Candidate trials retain author/compute authority checks.
Examples
accepted-run
One accepted scalar run, followed through coherent queued, running and terminal observations. Replay returns the original queued receipt, not the current inspection.
{ "expected_publication_id": "scalar-double-r1", "inputs": { "value": 2 }, "model_id": "scalar-double"}invalid-scientific-input
Only authorized scientific validation failures include bounded scientific-schema violations; authentication errors do not.
{ "expected_publication_id": "scalar-double-r1", "inputs": { "value": "wrong scientific type" }, "model_id": "scalar-double"}replayed-acceptance
One accepted scalar run, followed through coherent queued, running and terminal observations. Replay returns the original queued receipt, not the current inspection.
{ "expected_publication_id": "scalar-double-r1", "inputs": { "value": 2 }, "model_id": "scalar-double"}Named file properties vary by request; the request JSON maps those names to schema-declared inputs. File bodies are raw bytes, never JSON/base64 strings.
object
Fully specified inputs for one exact publication; ownership comes from authentication.
object
Exact publication: current-publication precondition for standard runs, explicit candidate for trials.
Required JSON value, including null when allowed by the publication schema. JSON Schema default annotations do not populate omitted inputs.
Stable catalog model identity.
Immutable submission intent. Candidate trials retain author/compute authority checks.
Responses
Section titled “Responses”One run was durably accepted. Equivalent retries return the same initial receipt, even if the run has since progressed. Location identifies its run-detail resource.
The original creation receipt, replayed even after the run progresses. Current run state is a separate inspection concern.
object
Acceptance time in UTC, formatted as RFC 3339.
Immutable submission intent. Candidate trials retain author/compute authority checks.
Initial accepted state, always queued; replay is not a fresh observation.
Examples
accepted-run
One accepted scalar run, followed through coherent queued, running and terminal observations. Replay returns the original queued receipt, not the current inspection.
{ "created_at": "2026-11-02T10:00:00Z", "model_id": "scalar-double", "publication_id": "scalar-double-r1", "purpose": "standard", "run_id": "00000000-0000-4000-8000-000000000001", "state": "queued"}replayed-acceptance
One accepted scalar run, followed through coherent queued, running and terminal observations. Replay returns the original queued receipt, not the current inspection.
{ "created_at": "2026-11-02T10:00:00Z", "model_id": "scalar-double", "publication_id": "scalar-double-r1", "purpose": "standard", "run_id": "00000000-0000-4000-8000-000000000001", "state": "queued"}Headers
Section titled “Headers”No-store
Relative run location: /api/v1/runs/{run_id}.
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
Malformed JSON/multipart framing, duplicate parts, unsupported part headers or query parameters (bad_request), or a missing, repeated, or invalid Idempotency-Key (invalid_idempotency_key).
The common JSON body for errors returned by the HTTP application.
object
Stable machine-readable error code.
Bounded corrections for authorized scientific-schema failures only. Absent on other failures. The complete validation error body is <=4608 bytes.
object
More violations exist than fit in this response.
At most eight violations, in validator traversal order.
A schema failure without submitted values or arbitrary property names.
object
Fixed guidance; actual bounds and allowed values remain in the publication schema.
JSON Pointer relative to inputs; the empty string denotes its root.
Only ordinary, explicitly declared property names and array indices appear.
Example
/valueThe position stops at a safe ancestor instead of naming the exact field.
Stable categories independent of the validator’s free-form diagnostics.
Safe explanation without internal errors or submitted input values.
Matches the response’s x-request-id header.
Headers
Section titled “Headers”No-store
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
A valid active user credential is required. Code unauthenticated.
The common JSON body for errors returned by the HTTP application.
object
Stable machine-readable error code.
Bounded corrections for authorized scientific-schema failures only. Absent on other failures. The complete validation error body is <=4608 bytes.
object
More violations exist than fit in this response.
At most eight violations, in validator traversal order.
A schema failure without submitted values or arbitrary property names.
object
Fixed guidance; actual bounds and allowed values remain in the publication schema.
JSON Pointer relative to inputs; the empty string denotes its root.
Only ordinary, explicitly declared property names and array indices appear.
The position stops at a safe ancestor instead of naming the exact field.
Stable categories independent of the validator’s free-form diagnostics.
Safe explanation without internal errors or submitted input values.
Matches the response’s x-request-id header.
Examples
unauthenticated-run
Only authorized scientific validation failures include bounded scientific-schema violations; authentication errors do not.
{ "code": "unauthenticated", "message": "A valid user bearer token is required.", "request_id": "00000000-0000-4000-8000-000000000012"}Headers
Section titled “Headers”No-store
Bearer
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
The credential does not allow run creation (insufficient_scope).
The common JSON body for errors returned by the HTTP application.
object
Stable machine-readable error code.
Bounded corrections for authorized scientific-schema failures only. Absent on other failures. The complete validation error body is <=4608 bytes.
object
More violations exist than fit in this response.
At most eight violations, in validator traversal order.
A schema failure without submitted values or arbitrary property names.
object
Fixed guidance; actual bounds and allowed values remain in the publication schema.
JSON Pointer relative to inputs; the empty string denotes its root.
Only ordinary, explicitly declared property names and array indices appear.
Example
/valueThe position stops at a safe ancestor instead of naming the exact field.
Stable categories independent of the validator’s free-form diagnostics.
Safe explanation without internal errors or submitted input values.
Matches the response’s x-request-id header.
Headers
Section titled “Headers”No-store
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
The exact publication is absent or inaccessible. Code not_found.
The common JSON body for errors returned by the HTTP application.
object
Stable machine-readable error code.
Bounded corrections for authorized scientific-schema failures only. Absent on other failures. The complete validation error body is <=4608 bytes.
object
More violations exist than fit in this response.
At most eight violations, in validator traversal order.
A schema failure without submitted values or arbitrary property names.
object
Fixed guidance; actual bounds and allowed values remain in the publication schema.
JSON Pointer relative to inputs; the empty string denotes its root.
Only ordinary, explicitly declared property names and array indices appear.
Example
/valueThe position stops at a safe ancestor instead of naming the exact field.
Stable categories independent of the validator’s free-form diagnostics.
Safe explanation without internal errors or submitted input values.
Matches the response’s x-request-id header.
Headers
Section titled “Headers”No-store
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
The multipart HTTP body did not finish within 60 seconds. Code request_timeout; no work was accepted.
The common JSON body for errors returned by the HTTP application.
object
Stable machine-readable error code.
Bounded corrections for authorized scientific-schema failures only. Absent on other failures. The complete validation error body is <=4608 bytes.
object
More violations exist than fit in this response.
At most eight violations, in validator traversal order.
A schema failure without submitted values or arbitrary property names.
object
Fixed guidance; actual bounds and allowed values remain in the publication schema.
JSON Pointer relative to inputs; the empty string denotes its root.
Only ordinary, explicitly declared property names and array indices appear.
Example
/valueThe position stops at a safe ancestor instead of naming the exact field.
Stable categories independent of the validator’s free-form diagnostics.
Safe explanation without internal errors or submitted input values.
Matches the response’s x-request-id header.
Headers
Section titled “Headers”No-store
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
Conflicting operation key (idempotency_conflict), changed expected publication (publication_changed), unavailable publication (publication_unavailable).
The common JSON body for errors returned by the HTTP application.
object
Stable machine-readable error code.
Bounded corrections for authorized scientific-schema failures only. Absent on other failures. The complete validation error body is <=4608 bytes.
object
More violations exist than fit in this response.
At most eight violations, in validator traversal order.
A schema failure without submitted values or arbitrary property names.
object
Fixed guidance; actual bounds and allowed values remain in the publication schema.
JSON Pointer relative to inputs; the empty string denotes its root.
Only ordinary, explicitly declared property names and array indices appear.
Example
/valueThe position stops at a safe ancestor instead of naming the exact field.
Stable categories independent of the validator’s free-form diagnostics.
Safe explanation without internal errors or submitted input values.
Matches the response’s x-request-id header.
Headers
Section titled “Headers”No-store
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
The request, multipart JSON part, attachment count/file size or input JSON exceeds its finite byte or decimal-storage budget. Code payload_too_large.
The common JSON body for errors returned by the HTTP application.
object
Stable machine-readable error code.
Bounded corrections for authorized scientific-schema failures only. Absent on other failures. The complete validation error body is <=4608 bytes.
object
More violations exist than fit in this response.
At most eight violations, in validator traversal order.
A schema failure without submitted values or arbitrary property names.
object
Fixed guidance; actual bounds and allowed values remain in the publication schema.
JSON Pointer relative to inputs; the empty string denotes its root.
Only ordinary, explicitly declared property names and array indices appear.
Example
/valueThe position stops at a safe ancestor instead of naming the exact field.
Stable categories independent of the validator’s free-form diagnostics.
Safe explanation without internal errors or submitted input values.
Matches the response’s x-request-id header.
Headers
Section titled “Headers”No-store
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
A JSON or multipart/form-data content type is required. Code unsupported_media_type.
The common JSON body for errors returned by the HTTP application.
object
Stable machine-readable error code.
Bounded corrections for authorized scientific-schema failures only. Absent on other failures. The complete validation error body is <=4608 bytes.
object
More violations exist than fit in this response.
At most eight violations, in validator traversal order.
A schema failure without submitted values or arbitrary property names.
object
Fixed guidance; actual bounds and allowed values remain in the publication schema.
JSON Pointer relative to inputs; the empty string denotes its root.
Only ordinary, explicitly declared property names and array indices appear.
Example
/valueThe position stops at a safe ancestor instead of naming the exact field.
Stable categories independent of the validator’s free-form diagnostics.
Safe explanation without internal errors or submitted input values.
Matches the response’s x-request-id header.
Headers
Section titled “Headers”No-store
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
The envelope or identifiers are invalid (invalid_request), inputs violate their schema, reference shape, storage, or nesting restrictions (invalid_inputs), an artifact is missing, private, not ready, or incompatible (invalid_artifact_input), or stored attachment evidence does not match (upload_verification_failed). Authorized schema failures include bounded position/rule/correction details; other failures omit details.
The common JSON body for errors returned by the HTTP application.
object
Stable machine-readable error code.
Bounded corrections for authorized scientific-schema failures only. Absent on other failures. The complete validation error body is <=4608 bytes.
object
More violations exist than fit in this response.
At most eight violations, in validator traversal order.
A schema failure without submitted values or arbitrary property names.
object
Fixed guidance; actual bounds and allowed values remain in the publication schema.
JSON Pointer relative to inputs; the empty string denotes its root.
Only ordinary, explicitly declared property names and array indices appear.
The position stops at a safe ancestor instead of naming the exact field.
Stable categories independent of the validator’s free-form diagnostics.
Safe explanation without internal errors or submitted input values.
Matches the response’s x-request-id header.
Examples
invalid-scientific-input
Only authorized scientific validation failures include bounded scientific-schema violations; authentication errors do not.
{ "code": "invalid_inputs", "details": { "truncated": false, "violations": [ { "correction": "Use a number.", "position": "/value", "position_redacted": false, "rule": "type" } ] }, "message": "Inputs do not satisfy the publication schema or supported JSON storage limits.", "request_id": "00000000-0000-4000-8000-000000000013"}Headers
Section titled “Headers”No-store
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
The service queue, user’s queue or multipart capacity is full. Codes queue_full, user_queue_full and multipart_busy.
The common JSON body for errors returned by the HTTP application.
object
Stable machine-readable error code.
Bounded corrections for authorized scientific-schema failures only. Absent on other failures. The complete validation error body is <=4608 bytes.
object
More violations exist than fit in this response.
At most eight violations, in validator traversal order.
A schema failure without submitted values or arbitrary property names.
object
Fixed guidance; actual bounds and allowed values remain in the publication schema.
JSON Pointer relative to inputs; the empty string denotes its root.
Only ordinary, explicitly declared property names and array indices appear.
Example
/valueThe position stops at a safe ancestor instead of naming the exact field.
Stable categories independent of the validator’s free-form diagnostics.
Safe explanation without internal errors or submitted input values.
Matches the response’s x-request-id header.
Headers
Section titled “Headers”No-store
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
Authentication or submission is unavailable; storage_not_configured means no managed upload destination is selected. Code submission_uncertain means the commit outcome is unknown: retry the same key and semantic request.
The common JSON body for errors returned by the HTTP application.
object
Stable machine-readable error code.
Bounded corrections for authorized scientific-schema failures only. Absent on other failures. The complete validation error body is <=4608 bytes.
object
More violations exist than fit in this response.
At most eight violations, in validator traversal order.
A schema failure without submitted values or arbitrary property names.
object
Fixed guidance; actual bounds and allowed values remain in the publication schema.
JSON Pointer relative to inputs; the empty string denotes its root.
Only ordinary, explicitly declared property names and array indices appear.
Example
/valueThe position stops at a safe ancestor instead of naming the exact field.
Stable categories independent of the validator’s free-form diagnostics.
Safe explanation without internal errors or submitted input values.
Matches the response’s x-request-id header.
Headers
Section titled “Headers”No-store
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
default
Section titled “default”An HTTP request failed; inspect the stable error code and request ID.
The common JSON body for errors returned by the HTTP application.
object
Stable machine-readable error code.
Bounded corrections for authorized scientific-schema failures only. Absent on other failures. The complete validation error body is <=4608 bytes.
object
More violations exist than fit in this response.
At most eight violations, in validator traversal order.
A schema failure without submitted values or arbitrary property names.
object
Fixed guidance; actual bounds and allowed values remain in the publication schema.
JSON Pointer relative to inputs; the empty string denotes its root.
Only ordinary, explicitly declared property names and array indices appear.
Example
/valueThe position stops at a safe ancestor instead of naming the exact field.
Stable categories independent of the validator’s free-form diagnostics.
Safe explanation without internal errors or submitted input values.
Matches the response’s x-request-id header.
Headers
Section titled “Headers”No-store
Always present. A fresh server-generated UUID for this request; incoming IDs are ignored. On errors, this equals the response body’s request_id.
Documentation 205dcb3116ea · public sources 8c70356d340f · built .Download documentation identity.