Executions endpoint

Queue workflow execution

POST/execution-runs/

Request body

application/json

See the request guidance below for a valid body.

cURL template

curl --fail-with-body \
  -H "Authorization: Bearer ${AKOFLOW_API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  -X POST \
  "${AKOFLOW_API_URL}/execution-runs/"

Supply a valid request.json before running this command.

202 Acceptedapplication/json

Handler-checked response shape; values and optional fields vary.

{
  "id": "queue-job-id",
  "category": "execution",
  "eventType": "execution.run.requested",
  "aggregateType": "execution_run",
  "aggregateId": "run-id",
  "status": "pending",
  "priority": 0,
  "availableAt": "2026-01-01T00:00:00Z",
  "attempts": 0,
  "maxAttempts": 5,
  "idempotencyKey": "execution-run:run-id",
  "createdAt": "2026-01-01T00:00:00Z"
}

Runnable SimGrid request

The first-run tutorial submits akoflow-examples/simulation/execution-request.yaml in a six-request sequence. Follow that order so referenced IDs exist.

Handler-checked behavior

202 Accepted publishes a queue job. The returned id is the job ID, while aggregateId is the submitted run.id. The worker validates the request before saving a run; GET /execution-runs/{runId}/ can return 404 until then, or remain 404 if validation fails. Use the original run.id to read the run, and do not treat the queue job's status as the run's status. Repeating the same run.id returns the existing idempotent job rather than creating a second one.

Response shape

This is the queue job for a new request, not the execution-run record. id identifies the job; aggregateId matches the submitted run.id. Queue status may advance while the daemon works, and optional lease/completion fields appear later. A run is saved only after the worker validates the request.

Related guide

See the Executions guide for related tasks and context.