Documentation menu
Projects

Invoke an operation

POST /api/v1/projects/{projectId}/environments/{environmentId}/operations/{definitionIdOrName}/invocations

Execute an operation from the selected deployment. Saturated Environment or API-process invocation capacity returns 429 or 503 with Retry-After before runtime execution begins. Definition data constraint failures return 422 with details.invocationId and a safe details.diagnostic. Inspect persisted diagnostics through the operation invocation list. A required auto-managed field must be included in the deployed domain's auto declarations; it must not be supplied manually. Infrastructure failures remain server errors, not input validation errors. An invocation that waited behind a runtime cutover returns 409 with details.retryable true and details.conflictReason runtime_cutover_busy and writes nothing. An invocation that fails the runtime generation fence because the Environment was activated or moved is retried once against the refreshed Environment pointer; a second fence failure returns 409 with details.retryable true and details.conflictReason runtime_generation_changed and writes nothing. A requestKey replay of a Command already committed under an earlier Deployment returns the stored result; a requestKey reused for a different intent returns 409 with details.conflictReason idempotency_key_reused. A Deployment whose stored definitions no longer compile returns 409 deployment_not_compilable with details.deploymentId and details.diagnosticCodes and writes nothing; push corrected definitions and deploy again.

Parameters

path

NameTypeRequiredDescription
projectIdstringrequiredIdentifies the Project that owns the addressed resource. Applies to Invoke an operation.
environmentIdstringrequiredIdentifies the Project environment addressed by the operation. Applies to Invoke an operation.
definitionIdOrNameone of 2 typesrequiredIdentifies the definition element by its stable identifier or name. Applies to Invoke an operation.

Request body

Required — Request body for: Invoke an operation.

application/json

NameTypeRequiredDescription
agentIdstringrequired
minPositionstringoptionalQueries only: wait up to two seconds for this Environment position.
paramsobjectoptional
actorUserIdstringoptional
approvalIdstringoptional
requestKeystringoptional

Responses

StatusDescriptionBody
200Response for status 200application/json — one of 2 types
202Response for status 202application/json — object — invocationId: string (required); outcome: object (required)
400The request is malformed or cannot be processed.application/json — PublicApiError — error: object (required)
401Authentication failed. The Authorization header is missing, or the credential is invalid or expired.application/json — PublicApiError — error: object (required)
403Access denied. The authenticated user does not have permission to perform this action.application/json — PublicApiError — error: object (required)
404Resource not found.application/json — PublicApiError — error: object (required)
409Request conflicts with current state of the resource, including safe deployment conflict classifications.application/json — PublicApiError — error: object (required)
422Request validation failed. Check the request body, query parameters, or path parameters.application/json — PublicApiError — error: object (required)
429Too many requests.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.application/json — PublicApiError — error: object (required)