> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentruntime.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> REST endpoints, request shapes, and interactive API explorer for AgentRuntime.

The AgentRuntime public API is served by the BFF at **`https://api.agentruntime.io`**. All customer integrations should use this base URL.

For request/response samples, see [API examples](/api/examples).

## Interactive explorer

Browse a subset of workflow and run endpoints in the marketing site's Scalar UI:

**[agentruntime.io/api-reference](https://agentruntime.io/api-reference)**

<Note>
  The marketing OpenAPI spec covers core workflow surfaces. It may lag behind the full BFF route catalog. Cross-check with the tables below or test against `api.agentruntime.io`.
</Note>

## OpenAPI specifications

Formal OpenAPI 3.1 specs exist for a subset of the API surface, including billing (`/v1/billing/*`) and onboarding (`/v1/onboarding/*`, `/v1/setup/*`) endpoints. There is no single full OpenAPI file covering every route today — use this page, [API examples](/api/examples), and the interactive explorer above for the rest of the surface.

## Authentication

All authenticated requests use either:

* **Session cookie** — Browser sessions from the Console
* **Bearer PAT** — `Authorization: Bearer pat_...` for programmatic access

Scoped requests also require:

```
X-Tenant-Id: your-workspace-slug
X-Project-Id: your-project-id
```

See [API authentication](/api/authentication).

Role shorthand in tables: **viewer+** = `project_viewer` or higher, **contributor+** = `project_contributor` or higher, **tenant\_admin** = workspace billing admin.

***

## Workflows

Base path: `/v1/workflows`

| Method   | Path                          | Role         | Description                                          |
| -------- | ----------------------------- | ------------ | ---------------------------------------------------- |
| `GET`    | `/v1/workflows`               | viewer+      | List workflows                                       |
| `POST`   | `/v1/workflows`               | contributor+ | Create workflow                                      |
| `GET`    | `/v1/workflows/{id}`          | viewer+      | Get workflow                                         |
| `PATCH`  | `/v1/workflows/{id}`          | contributor+ | Update draft graph or **run\_setup** (Save defaults) |
| `DELETE` | `/v1/workflows/{id}`          | contributor+ | Archive workflow                                     |
| `POST`   | `/v1/workflows/{id}/versions` | contributor+ | Publish version                                      |
| `GET`    | `/v1/workflows/{id}/versions` | viewer+      | List versions                                        |
| `POST`   | `/v1/workflows/{id}/validate` | contributor+ | Dry-run graph validation                             |
| `POST`   | `/v1/workflows/{id}/command`  | contributor+ | Run control (see below)                              |
| `GET`    | `/v1/workflows/{id}/runs`     | viewer+      | List runs for workflow                               |
| `GET`    | `/v1/workflows/{id}/stream`   | viewer+      | WebSocket event stream                               |

### Start, pause, resume, stop

`POST /v1/workflows/{id}/command`

```json theme={null}
{
  "command": "start",
  "params": {
    "trigger_type": "api",
    "trigger_payload": {
      "topic": "weekly digest",
      "message": "Hello"
    },
    "trigger_steps": {
      "step-uuid-optional": { "prompt": "per-step override" }
    },
    "use_run_setup_defaults": false
  }
}
```

| Param                    | Description                                                                                                             |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `trigger_payload`        | Global shared input → `{{input.*}}`                                                                                     |
| `trigger_steps`          | Per-step map (optional overrides / gated entry grants)                                                                  |
| `use_run_setup_defaults` | When `true`, merge saved Studio defaults from the workflow version; **request keys win** on conflicts. Default `false`. |

`params` become workflow **input** (`{{input.*}}` in steps). See [Run setup](/workflows/run-setup).

| `command` | `params`                  | Effect                                        |
| --------- | ------------------------- | --------------------------------------------- |
| `start`   | Trigger fields            | Start a new run                               |
| `pause`   | `run_id`                  | Pause scheduling                              |
| `resume`  | `run_id`                  | Resume paused run                             |
| `stop`    | `run_id`, optional `mode` | Stop run (`immediate` default, or `graceful`) |

### Runs and human tasks

| Method | Path                                                       | Role         | Description                                       |
| ------ | ---------------------------------------------------------- | ------------ | ------------------------------------------------- |
| `GET`  | `/v1/runs`                                                 | viewer+      | Tenant-wide run feed (Command Center data source) |
| `GET`  | `/v1/workflows/{id}/runs/{runID}/events`                   | viewer+      | Step event log                                    |
| `GET`  | `/v1/workflows/{id}/runs/{runID}/context`                  | viewer+      | Run variables and step results                    |
| `GET`  | `/v1/tasks/pending`                                        | viewer+      | Pending human tasks (tenant inbox)                |
| `GET`  | `/v1/workflows/{id}/runs/{runID}/tasks/pending`            | contributor+ | Pending tasks for one run                         |
| `POST` | `/v1/workflows/{id}/runs/{runID}/tasks/{task_id}/complete` | contributor+ | Approve or reject human task                      |

Complete task body:

```json theme={null}
{
  "approved": true,
  "result": {
    "comment_body": "Optional fields merged into step result"
  }
}
```

The human task step result always includes `approved`. The Console Approve/Reject buttons send only `{ "approved": true|false }`. See [Human tasks](/workflows/human-tasks#what-downstream-steps-receive).

<h3 id="run-event-types">
  Run event types
</h3>

Persisted on `GET /v1/workflows/{id}/runs/{runID}/events`. See also [Runs and Command Center — Failure handling](/workflows/runs-and-command-center#failure-handling).

| `event_type`                   | Description                                              |
| ------------------------------ | -------------------------------------------------------- |
| `step_started`                 | Step began                                               |
| `step_completed`               | Step succeeded, or synthetic skip (`data.skipped: true`) |
| `step_failed`                  | Step error; run may transition to `failed`               |
| `step_cancelled`               | Step was in flight when another step failed the run      |
| `state_changed`                | Run status transition                                    |
| `run_started` / `run_rejected` | Run lifecycle                                            |

**Skip reasons** on `step_completed` when `skipped: true`:

| `reason`        | Meaning                             |
| --------------- | ----------------------------------- |
| `blocked`       | Run failed before this step started |
| `out_of_scope`  | Episode mode — step outside scope   |
| `step_disabled` | Step disabled in graph              |

**Cancelled step** (`step_cancelled`): `data.cancelled: true`, `data.reason: "run_failed"`, optional `caused_by_step_id`.

See [Runs and Command Center — Failure handling](/workflows/runs-and-command-center#failure-handling) for Console badges.

***

## Inbound webhooks

| Method   | Path                                     | Auth              | Description                     |
| -------- | ---------------------------------------- | ----------------- | ------------------------------- |
| `POST`   | `/v1/inbound-webhooks`                   | contributor+      | Create subscription             |
| `GET`    | `/v1/inbound-webhooks`                   | contributor+      | List subscriptions              |
| `DELETE` | `/v1/inbound-webhooks/{id}`              | contributor+      | Delete subscription             |
| `POST`   | `/v1/inbound-webhooks/{subscription_id}` | HMAC + Bearer PAT | **Public ingress** — starts run |

Create subscription:

```json theme={null}
{
  "workflow_id": "workflow-uuid",
  "name": "form-leads",
  "automation_pat_id": "optional-stored-pat-id",
  "automation_bearer": "pat_…"
}
```

Response includes `ingress_url`, `signing_secret` (once), and `subscription`.

Ingress request headers:

* `Authorization: Bearer pat_…`
* `X-Agentruntime-Signature: sha256=<hmac-sha256 of raw body>`
* `Content-Type: application/json`

See [Inbound webhooks](/integrations/inbound-webhooks).

***

## Connections

Base path: `/v1/connections` — **project\_contributor**

| Method   | Path                               | Description                                   |
| -------- | ---------------------------------- | --------------------------------------------- |
| `GET`    | `/v1/connections`                  | List workspace connections                    |
| `POST`   | `/v1/connections`                  | Create custom connection                      |
| `PATCH`  | `/v1/connections/{id}`             | Update connection                             |
| `DELETE` | `/v1/connections/{id}`             | Delete connection                             |
| `GET`    | `/v1/connections/{id}/credentials` | Reveal credential metadata (not full secrets) |

### Google OAuth

| Method  | Path                                                      | Description                       |
| ------- | --------------------------------------------------------- | --------------------------------- |
| `GET`   | `/v1/connections/google/config`                           | Whether Google connect is enabled |
| `POST`  | `/v1/connections/google/oauth-url`                        | Start OAuth                       |
| `POST`  | `/v1/connections/google/complete`                         | Complete OAuth callback           |
| `GET`   | `/v1/connections/google/accounts/{connectionId}`          | Account + enabled services        |
| `PATCH` | `/v1/connections/google/accounts/{connectionId}/services` | Enable/disable services           |

### WhatsApp

| Method | Path                                | Description                         |
| ------ | ----------------------------------- | ----------------------------------- |
| `GET`  | `/v1/connections/whatsapp/config`   | Whether WhatsApp connect is enabled |
| `POST` | `/v1/connections/whatsapp/complete` | Complete embedded signup            |
| `POST` | `/v1/connections/whatsapp/manual`   | Manual WABA credentials             |

***

## MCP

Base path: `/v1/mcp` — **project\_contributor** unless noted.

### Servers and catalog

| Method | Path                                                        | Description                 |
| ------ | ----------------------------------------------------------- | --------------------------- |
| `GET`  | `/v1/mcp/platform-catalog`                                  | Platform adapter catalog    |
| `GET`  | `/v1/mcp/tools`                                             | Tool catalog                |
| `GET`  | `/v1/mcp/servers`                                           | Tenant MCP servers          |
| `POST` | `/v1/mcp/servers`                                           | Register tenant server      |
| `GET`  | `/v1/mcp/servers/{id}`                                      | Server detail               |
| `POST` | `/v1/mcp/servers/{id}/validate`                             | Run validation checks       |
| `POST` | `/v1/mcp/servers/{id}/connections/{connection_id}/validate` | Validate connection binding |

### Instances and config profiles

| Method  | Path                                                             | Description                    |
| ------- | ---------------------------------------------------------------- | ------------------------------ |
| `GET`   | `/v1/mcp/instances`                                              | List instances                 |
| `POST`  | `/v1/mcp/instances`                                              | Create instance                |
| `POST`  | `/v1/mcp/instances/resolve`                                      | Resolve instances for workflow |
| `GET`   | `/v1/mcp/instances/{id}/config-profiles`                         | List profiles                  |
| `POST`  | `/v1/mcp/instances/{id}/config-profiles`                         | Create profile                 |
| `PATCH` | `/v1/mcp/instances/{id}/config-profiles/{profile_id}`            | Update profile wiring          |
| `POST`  | `/v1/mcp/instances/{id}/config-profiles/{profile_id}/set-active` | Set active profile             |

Duplicate connection CRUD also exists under `/v1/mcp/connections` for legacy clients.

***

## AI, chat, and memory

| Method     | Path                            | Role         | Description        |
| ---------- | ------------------------------- | ------------ | ------------------ |
| `POST`     | `/v1/autopilot/chat`            | viewer+      | Autopilot message  |
| `GET`      | `/v1/autopilot/stream`          | viewer+      | Streaming response |
| `GET/POST` | `/v1/chat/*`                    | viewer+      | Chat service proxy |
| `GET`      | `/v1/llm-provider-keys/catalog` | viewer+      | LLM model catalog  |
| `POST`     | `/v1/llm/resolve`               | contributor+ | Resolve model ref  |

### Memory (preview)

<Note>
  Memory routes require memory kernel configuration. Console Memory UI may be off in production — see [Feature availability](/platform/feature-availability).
</Note>

| Method | Path                            | Description            |
| ------ | ------------------------------- | ---------------------- |
| `POST` | `/v1/memory/search`             | Semantic search        |
| `POST` | `/v1/memory/index-conversation` | Index chat episode     |
| `POST` | `/v1/memory/index-file`         | Index work file        |
| `POST` | `/v1/memory/extract/batch`      | Batch extract jobs     |
| `GET`  | `/v1/memory/extract/{jobId}`    | Extract job status     |
| `POST` | `/v1/memory/tools/call`         | Agent memory tool call |

***

## Billing endpoints

Base path: `/v1/billing`

| Method | Path                                         | Role          | Description                                                       |
| ------ | -------------------------------------------- | ------------- | ----------------------------------------------------------------- |
| `GET`  | `/v1/billing/summary`                        | contributor+  | Tenant/project summary                                            |
| `GET`  | `/v1/billing/plans`                          | contributor+  | Plan catalog for this deployment's `product_code` (Stripe-synced) |
| `GET`  | `/v1/billing/status`                         | contributor+  | Subscription and trial status                                     |
| `GET`  | `/v1/billing/usage`                          | contributor+  | Credit balances (microcredits)                                    |
| `GET`  | `/v1/billing/usage-dimensions`               | viewer+       | Usage breakdown dimensions                                        |
| `GET`  | `/v1/billing/usage-history`                  | contributor+  | Metered usage ledger                                              |
| `GET`  | `/v1/billing/payment-history`                | contributor+  | Payments and top-ups                                              |
| `GET`  | `/v1/billing/action-pricing`                 | contributor+  | Resolved per-action prices                                        |
| `POST` | `/v1/billing/topups/payg/intent`             | contributor+  | PAYG top-up Stripe intent                                         |
| `POST` | `/v1/billing/trial`                          | tenant\_admin | Start trial                                                       |
| `POST` | `/v1/billing/subscription`                   | tenant\_admin | Activate subscription                                             |
| `POST` | `/v1/billing/subscription/change-plan`       | tenant\_admin | Change plan                                                       |
| `POST` | `/v1/billing/subscription/cancel`            | tenant\_admin | Cancel at period end (default)                                    |
| `POST` | `/v1/billing/subscription/convert-trial-now` | tenant\_admin | End trial early                                                   |
| `POST` | `/v1/billing/codes/apply`                    | tenant\_admin | Apply billing code                                                |
| `POST` | `/v1/billing/discounts/validate`             | tenant\_admin | Validate discount                                                 |

`GET /v1/config/stripe` — publishable Stripe config for Console checkout.

`GET /v1/billing/plans` returns tiers scoped to your workspace's product (AgentRuntime Console → `agentruntime`). Catalog rows are keyed by `(product_code, plan_code)`; the public response surfaces `plan_code` and pricing fields. See [Multi-product billing](/platform/multi-product-billing).

See [Billing and credits](/platform/billing-and-credits) and [API examples](/api/examples).

***

## Agents

Base path: `/v1/agents` — **project\_viewer** (read), **project\_contributor** (write). Requires `enableAgents` in your deployment.

| Method   | Path              | Description  |
| -------- | ----------------- | ------------ |
| `GET`    | `/v1/agents`      | List agents  |
| `POST`   | `/v1/agents`      | Create agent |
| `GET`    | `/v1/agents/{id}` | Get agent    |
| `PATCH`  | `/v1/agents/{id}` | Update agent |
| `DELETE` | `/v1/agents/{id}` | Delete agent |

***

## Analytics

Base path: `/v1/analytics` — **project\_contributor**

| Endpoint                           | Metric                          |
| ---------------------------------- | ------------------------------- |
| `/v1/analytics/live-runs`          | Currently running workflows     |
| `/v1/analytics/success-rate`       | Run success percentage          |
| `/v1/analytics/execution-duration` | Wall-clock execution time       |
| `/v1/analytics/runs-count`         | Runs in selected window         |
| `/v1/analytics/steps-executed`     | Metered workflow steps          |
| `/v1/analytics/credits-consumed`   | Credits used in window          |
| `/v1/analytics/steps-summary`      | Step-type breakdown and latency |
| `/v1/analytics/runs-timeseries`    | Run count over time             |
| `/v1/analytics/usage-timeseries`   | Usage over time                 |

Query `window=month|week|all` or bounded `from` / `to` with optional granularity on timeseries endpoints. See [Analytics](/platform/analytics).

***

## Personal access tokens

| Method   | Path                   | Role         | Description         |
| -------- | ---------------------- | ------------ | ------------------- |
| `GET`    | `/v1/pats`             | contributor+ | List tokens         |
| `POST`   | `/v1/pats`             | contributor+ | Create token        |
| `GET`    | `/v1/pats/{id}/reveal` | viewer+      | Reveal token (once) |
| `DELETE` | `/v1/pats/{id}`        | contributor+ | Revoke token        |

Console **Settings → API keys** manages the same keys for inbound webhook automation.

***

## Error codes

| Status | Meaning                                     |
| ------ | ------------------------------------------- |
| `401`  | Missing or invalid authentication           |
| `403`  | Insufficient project role or PAT scope      |
| `404`  | Resource not found                          |
| `422`  | Validation error (graph, bindings, billing) |
| `429`  | Rate limited                                |
| `5xx`  | Server error — retry with backoff           |

***

## SDKs and collections

* **Request/response samples** — see [API examples](/api/examples) for copy-paste requests
* **Platform MCP** — [mcp.agentruntime.io](https://mcp.agentruntime.io/mcp); see [Platform MCP](/api/platform-mcp)

Contact [support@agentruntime.io](mailto:support@agentruntime.io) for enterprise API SLAs.