Executions API

Endpoint reference for creating, listing, cancelling executions and fetching tasks, agents, and artifacts.

Full reference for Integration API execution and discovery endpoints. All requests require Authorization: Bearer ra_live_....

Create execution

POST /api/v1/integrations/executions

Headers

Header	Required	Purpose
`Authorization`	Yes	Bearer API key
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Prevent duplicate runs on retry

Query parameters

Parameter	Purpose
`validate_only=true`	Validate without queuing

Request body

{
  "agent_id": "uuid",
  "task_id": "uuid",
  "task_version_id": "uuid",
  "version": "current",
  "params": { "key": "value" },
  "reference": "ORD-12345",
  "metadata": { "source": "erp" },
  "callback_url": "https://api.example.com/hooks/rearray",
  "scheduled_at": "2026-06-15T09:00:00+00:00",
  "priority": 10
}

Field	Required	Description
`agent_id`	Yes	Agent that executes the run
`task_id`	One of	Task to run
`task_version_id`	One of	Specific version UUID
`version`	No	Version number or `"current"`
`params`	No	Input values validated against params schema
`reference`	No	Caller correlation ID (1–255 chars)
`metadata`	No	Free-form JSON (max 8 KB, 50 keys, values ≤ 500 chars)
`callback_url`	No	HTTPS URL for webhook callbacks
`scheduled_at`	No	ISO 8601 deferred start time
`priority`	No	Queue priority -1000 to 1000 (default 0)

Metadata keys may not start with _rearray..

Responses

201 Created — Execution queued:

{
  "execution_id": "uuid",
  "status": "queued",
  "reference": "ORD-12345",
  "metadata": { "source": "erp" },
  "task_id": "uuid",
  "task_version_id": "uuid",
  "scheduled_at": null,
  "priority": 10,
  "request_id": "req_..."
}

200 OK — Idempotent replay (Idempotency-Key match):

{
  "execution_id": "uuid",
  "status": "completed",
  "idempotent_replay": true,
  "request_id": "req_..."
}

200 OK — validate_only=true:

{
  "would_create": true,
  "status": "would_create",
  "request_id": "req_..."
}

422 — Validation error (invalid params, missing task, scope violation).

Example

curl -X POST https://your-app.example.com/api/v1/integrations/executions \
  -H "Authorization: Bearer ra_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ord-123-create" \
  -d '{
    "agent_id": "00000000-0000-0000-0000-000000000001",
    "task_id": "00000000-0000-0000-0000-000000000002",
    "params": { "orderId": "ORD-123" },
    "reference": "ORD-123",
    "callback_url": "https://api.example.com/hooks/rearray"
  }'

List executions

GET /api/v1/integrations/executions

Query parameters

Parameter	Description
`status`	Filter: `pending`, `queued`, `running`, `completed`, `cancelled`, `aborted`, `error`
`task_id`	Filter by task UUID
`agent_id`	Filter by agent UUID
`reference`	Filter by reference string
`from`	Created at ≥ (ISO 8601)
`to`	Created at ≤ (ISO 8601)
`cursor`	Pagination cursor from previous response
`limit`	Page size (default 50, max 200)

Response

{
  "data": [
    {
      "id": "uuid",
      "status": "completed",
      "task_id": "uuid",
      "task_version_id": "uuid",
      "agent_id": "uuid",
      "reference": "ORD-123",
      "metadata": {},
      "params": { "orderId": "ORD-123" },
      "result": { "status": "shipped" },
      "error_message": null,
      "started_at": "2026-06-12T10:00:00Z",
      "stopped_at": "2026-06-12T10:02:30Z",
      "created_at": "2026-06-12T09:59:55Z",
      "updated_at": "2026-06-12T10:02:30Z",
      "scheduled_at": null,
      "priority": 0
    }
  ],
  "next_cursor": "base64url-encoded-cursor",
  "request_id": "req_..."
}

Get execution

GET /api/v1/integrations/executions/{id}

Returns a single execution object (same shape as list items).

Cancel execution

POST /api/v1/integrations/executions/{id}/cancel

Cancels executions in pending, queued, or running status.

Get artifacts

GET /api/v1/integrations/executions/{id}/artifacts

Returns signed URLs for execution video artifacts. URLs expire after 5 minutes (expires_in_seconds: 300).

{
  "execution_id": "uuid",
  "status": "completed",
  "started_at": "2026-06-12T10:00:00Z",
  "stopped_at": "2026-06-12T10:02:30Z",
  "videos": [
    {
      "platform_id": "uuid",
      "handler": "portal",
      "started_offset_ms": 0,
      "storage_key": "path/in/bucket",
      "signed_url": "https://...",
      "expires_in_seconds": 300,
      "error": null
    }
  ],
  "request_id": "req_..."
}

List tasks

GET /api/v1/integrations/tasks

Returns tasks the API key is allowed to execute (scoped by allowed_task_ids).

Get task

GET /api/v1/integrations/tasks/{id}

Returns task details including linked platforms and latest version info.

Get params schema

GET /api/v1/integrations/tasks/{id}/params-schema
GET /api/v1/integrations/tasks/{id}/params-schema?version=3

Returns the JSON Schema for task params. Use version query param for a specific version number.

List agents

GET /api/v1/integrations/agents

Returns agents the API key is allowed to use (scoped by allowed_agent_ids).