Executions API

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

Create execution

POST /api/v1/integrations/executions

Headers

Query parameters

Request body

{
  "agent_id": "uuid",
  "task_id": "uuid",
  "task_version_id": "uuid",
  "version": "current",
  "v": 3,
  "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
}

Metadata keys may not start with _rearray..

When more than one version selector is provided, precedence is task_version_id > v > version. If none is given, the task's current version is used.

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

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 one execution by UUID for the API key's account. Use this to poll status after create, or to load result and file artifacts without listing.

Path {id} must be a valid UUID. Unknown IDs and executions belonging to another account return 404 not_found.

Response

200 OK — Detail shape uses execution_id (not id) and includes file artifact arrays:

{
  "execution_id": "uuid",
  "status": "completed",
  "task_id": "uuid",
  "task_version_id": "uuid",
  "agent_id": "uuid",
  "reference": "ORD-123",
  "metadata": { "source": "erp" },
  "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,
  "downloads": [
    {
      "id": "uuid",
      "file_name": "invoice.pdf",
      "content_type": "application/pdf",
      "size_bytes": 10240,
      "url": "https://your-app.example.com/api/v1/integrations/executions/{id}/files/{fileId}"
    }
  ],
  "prints": [],
  "screenshots": [],
  "request_id": "req_..."
}

This endpoint does not return session video signed URLs — use Get artifacts for videos.

Example

curl https://your-app.example.com/api/v1/integrations/executions/00000000-0000-0000-0000-000000000099 \
  -H "Authorization: Bearer ra_live_your_key"

SDK: client.getExecution(id).

Cancel execution

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

Cancels executions in pending, queued, running, or awaiting_input status. Sets status to aborted.

{
  "execution_id": "uuid",
  "status": "aborted",
  "request_id": "req_..."
}

Get artifacts

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

Returns signed URLs for session videos, plus the same downloads / prints / screenshots file arrays as Get execution. Video signed URLs expire after 5 minutes (expires_in_seconds: 300). File url values are stable API-key-gated links (see Download execution file).

{
  "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
    }
  ],
  "downloads": [],
  "prints": [],
  "screenshots": [],
  "request_id": "req_..."
}

Download execution file

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

Downloads one file artifact (download, print, or screenshot) belonging to the execution. On success responds with 302 to a short-lived signed storage URL. Requires the same Bearer API key as other Integration endpoints. Unknown execution/file pairs (or cross-account) return 404.

curl -L https://your-app.example.com/api/v1/integrations/executions/{id}/files/{fileId} \
  -H "Authorization: Bearer ra_live_your_key" \
  -o invoice.pdf

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?v=3
GET /api/v1/integrations/tasks/{id}/params-schema?version=tag:stable

Returns the JSON Schema for task params. By default the task's current version is used. Use v for a specific version number, or version for "current", "tag:<name>", or a version UUID.

List agents

GET /api/v1/integrations/agents

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