Creates an aggregate run request that is interpreted by an LLM to resolve plans, environments, and platforms into a plan×environment entry matrix. Each entry becomes an independent QA run. The matrix is capped at 8 entries by default (server-side override: GITHUB_REQUEST_MAX_FANOUT env var). AI interpretation is billed once per request at provider cost plus 20%; providers without per-request cost use the current token price estimate. Provide `request` (natural language) for LLM-interpreted resolution, or `planIds`/`planNames` for structured resolution. At least one of these is required. Requires the autonomy:runs:write API key scope.

Creates an aggregate run request that is interpreted by an LLM to resolve plans, environments, and platforms into a plan×environment entry matrix. Each entry becomes an independent QA run. The matrix is capped at 8 entries by default (server-side override: GITHUB_REQUEST_MAX_FANOUT env var). AI interpretation is billed once per request at provider cost plus 20%; providers without per-request cost use the current token price estimate. Provide request (natural language) for LLM-interpreted resolution, or planIds/planNames for structured resolution. At least one of these is required. Requires the autonomy:runs:write API key scope.

Authorization

bearerAuth

AuthorizationBearer <token>

Send Authorization: Bearer . The token can be an Autonomy organization API key (aut_xxx) or an OAuth access token.

In: header

Header Parameters

Idempotency-Key?string

Idempotency key. If omitted, the server generates one. Re-sending the same key returns the original request without re-interpreting or re-billing.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

request?string

Natural-language request describing which plans to run and where. Mutually sufficient with planIds/planNames — provide at least one.

planIds?array<string>

Explicit test plan document IDs to run.

planNames?array<string>

Test plan names to resolve. Matched case-insensitively against saved plans.

environmentSlugs?array<string>

Environment slugs to target. When omitted, each plan uses its default environment.

urls?array<>

Explicit URLs to use as targets. Creates explicit_url entries in the matrix.

platforms?array<>

Platforms to run on. When omitted, inferred from the request text or plan defaults.

idempotencyKey?string

Idempotency key (alternative to the Idempotency-Key header). When a request with this key already exists, the original is returned (HTTP 200) without re-interpretation or re-billing.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/run-requests" \  -H "Content-Type: application/json" \  -d '{    "request": "Run checkout and login plans on staging",    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"  }'

{
  "requestId": "string",
  "status": "interpreting",
  "request": "string",
  "resolutionSource": "string",
  "rejectionReasons": [
    "string"
  ],
  "error": "string",
  "createdAt": 0,
  "completedAt": 0,
  "entries": [
    {
      "runId": "string",
      "testPlanId": "string",
      "planName": "string",
      "platforms": [
        "web"
      ],
      "target": {
        "kind": "environment",
        "slug": "string",
        "name": "string"
      },
      "queueError": "string",
      "runStatus": "string",
      "runError": "string"
    }
  ]
}

{
  "requestId": "string",
  "status": "interpreting",
  "request": "string",
  "resolutionSource": "string",
  "rejectionReasons": [
    "string"
  ],
  "error": "string",
  "createdAt": 0,
  "completedAt": 0,
  "entries": [
    {
      "runId": "string",
      "testPlanId": "string",
      "planName": "string",
      "platforms": [
        "web"
      ],
      "target": {
        "kind": "environment",
        "slug": "string",
        "name": "string"
      },
      "queueError": "string",
      "runStatus": "string",
      "runError": "string"
    }
  ]
}

{
  "error": "string"
}

{
  "error": "string"
}

Create a run request

Authorization

Header Parameters

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`

`application/json`