> ## 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 examples

> Copy-paste request and response samples for common AgentRuntime REST operations.

These examples use the public BFF at **`https://api.agentruntime.io`**. Replace tenant slug, project ID, workflow UUIDs, and tokens with your values.

All authenticated examples require:

```bash theme={null}
export AR_API="https://api.agentruntime.io"
export AR_TOKEN="pat_…"
export AR_TENANT="your-workspace-slug"
export AR_PROJECT="your-project-id"
```

```bash theme={null}
curl -sS "$AR_API/v1/workflows" \
  -H "Authorization: Bearer $AR_TOKEN" \
  -H "X-Tenant-Id: $AR_TENANT" \
  -H "X-Project-Id: $AR_PROJECT"
```

See [API authentication](/api/authentication) for PAT scopes and session cookies.

***

## Create a workflow

`POST /v1/workflows` — **project\_contributor**

**Request:**

```json theme={null}
{
  "name": "hello-mcp",
  "description": "Smoke test",
  "graph": {
    "steps": [
      {
        "id": "ping",
        "type": "lua_script",
        "name": "Echo input",
        "script": "return { message = 'ok', input = input }",
        "timeout_s": 10
      }
    ]
  }
}
```

**Response** (`201`):

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "hello-mcp",
  "description": "Smoke test",
  "tenant_id": "your-workspace-slug",
  "project_id": "your-project-id",
  "status": "draft",
  "graph": { "steps": ["…"] },
  "created_at": "2026-06-06T12:00:00Z",
  "updated_at": "2026-06-06T12:00:00Z"
}
```

***

## Publish a version

`POST /v1/workflows/{id}/versions` — **project\_contributor**

**Request:**

```json theme={null}
{
  "changelog": "Initial publish"
}
```

**Response** (`201`):

```json theme={null}
{
  "version": 1,
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "published_at": "2026-06-06T12:05:00Z",
  "graph_snapshot": { "steps": ["…"] }
}
```

Runs always execute a **published** snapshot, not draft edits.

***

## Start a run

`POST /v1/workflows/{id}/command` — **project\_contributor**

**Request:**

```json theme={null}
{
  "command": "start",
  "params": {
    "customer_email": "alex@example.com",
    "order_id": "12345"
  }
}
```

**Response** (`200`):

```json theme={null}
{
  "run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "running",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "started_at": "2026-06-06T12:10:00Z"
}
```

`params` become workflow **input** (`{{input.customer_email}}`, etc.).

### Pause, resume, stop

```json theme={null}
{ "command": "pause", "params": { "run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }
```

```json theme={null}
{ "command": "resume", "params": { "run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }
```

```json theme={null}
{ "command": "stop", "params": { "run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "mode": "graceful" } }
```

***

## Complete a human task

`POST /v1/workflows/{id}/runs/{runID}/tasks/{task_id}/complete` — **project\_contributor**

**Approve only** (Console default):

```json theme={null}
{
  "approved": true
}
```

**Approve with custom result fields:**

```json theme={null}
{
  "approved": true,
  "result": {
    "comment_body": "Edited review text posted to GitHub"
  }
}
```

**Response** (`200`):

```json theme={null}
{
  "status": "completed",
  "task_id": "approve-review",
  "approved": true
}
```

See [Human tasks](/workflows/human-tasks#what-downstream-steps-receive).

***

## Create inbound webhook subscription

`POST /v1/inbound-webhooks` — **project\_contributor**

**Request** (Vault-backed PAT id):

```json theme={null}
{
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "form-leads",
  "automation_pat_id": "pat-abc123"
}
```

**Request** (paste bearer once):

```json theme={null}
{
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "form-leads",
  "automation_pat_id": "pat-abc123",
  "automation_bearer": "pat_…"
}
```

**Response** (`201`):

```json theme={null}
{
  "subscription": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenant_id": "your-workspace-slug",
    "project_id": "your-project-id",
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "form-leads",
    "enabled": true,
    "created_at": "2026-06-06T12:00:00Z",
    "updated_at": "2026-06-06T12:00:00Z"
  },
  "signing_secret": "whsec_…",
  "ingress_url": "https://api.agentruntime.io/v1/inbound-webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ingress_path": "/v1/inbound-webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

`signing_secret` is returned **once**. List endpoints never include secrets.

### Public ingress (external sender)

`POST /v1/inbound-webhooks/{subscription_id}` — **HMAC + Bearer PAT** (no session cookie)

```bash theme={null}
BODY='{"email":"alex@example.com"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WHSEC" | sed 's/^.* //')
curl -X POST "$AR_API/v1/inbound-webhooks/$SUBSCRIPTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AR_TOKEN" \
  -H "X-Agentruntime-Signature: sha256=$SIG" \
  -d "$BODY"
```

***

## Create a custom connection

`POST /v1/connections` — **project\_contributor**

**Request:**

```json theme={null}
{
  "display_name": "GitHub CI",
  "provider": "custom",
  "service": "api_key",
  "credentials": {
    "api_key": "ghp_…"
  }
}
```

**Response** (`201`):

```json theme={null}
{
  "id": "conn-uuid",
  "name": "GitHub CI",
  "provider": "custom",
  "service": "api_key",
  "status": "active",
  "credential_keys": ["api_key"]
}
```

Secrets are stored in Vault; list/get responses do not return plaintext values.

***

## Register a custom MCP server

`POST /v1/mcp/servers` — **project\_contributor**

**Request:**

```json theme={null}
{
  "name": "Internal tools",
  "canonical_url": "https://tools.example.com/mcp",
  "mode": "third_party",
  "auth_mode": "token"
}
```

**Response** (`201`):

```json theme={null}
{
  "id": "server-uuid",
  "name": "Internal tools",
  "service": "internal_tools",
  "canonical_url": "https://tools.example.com/mcp",
  "status": "draft",
  "auth_mode": "token",
  "tool_count": 0
}
```

Follow with discover → publish version → validate → `POST /v1/mcp/instances`. See [Custom MCP servers](/integrations/custom-mcp-servers).

***

## Create a PAT

`POST /v1/pats` — **project\_contributor**

**Request:**

```json theme={null}
{
  "display_name": "CI deploy",
  "scopes": ["workflow:read", "workflow:run"]
}
```

**Response** (`201`):

```json theme={null}
{
  "id": "pat-metadata-id",
  "display_name": "CI deploy",
  "token": "pat_…",
  "scopes": ["workflow:read", "workflow:run"],
  "created_at": "2026-06-06T12:00:00Z"
}
```

`token` is shown **once**. Create keys in the Console under **Settings → API keys**.

***

## Billing usage snapshot

`GET /v1/billing/usage` — **project\_contributor**

**Response** (`200`):

```json theme={null}
{
  "trial_remaining": 2000000,
  "included_remaining": 10000000,
  "payg_remaining": 5000000,
  "total_remaining_microcredits": 17000000
}
```

Values are **microcredits** (1 credit = 1,000,000 microcredits). See [Billing and credits](/platform/billing-and-credits).

***

## Plan catalog (product-scoped)

`GET /v1/billing/plans` — **project\_contributor**

The BFF filters to its deployment `product_code` (`agentruntime` on `api.agentruntime.io`). Response omits `product_code` — it is implicit for this host.

**Response** (`200`, excerpt):

```json theme={null}
{
  "plans": [
    {
      "plan_code": "pro",
      "stripe_price_id": "price_1Example",
      "amount": 4900,
      "currency": "usd",
      "interval": "month",
      "interval_count": 1,
      "product_name": "AgentRuntime Pro",
      "trial_enabled": true,
      "trial_requires_card": false,
      "trial_days": 14,
      "trial_credits_granted": 5000000,
      "onboarding_default": true,
      "self_serve_onboarding": true
    },
    {
      "plan_code": "free",
      "amount": 0,
      "currency": "usd",
      "interval": "month",
      "interval_count": 1,
      "product_name": "AgentRuntime Free",
      "trial_enabled": false
    }
  ]
}
```

Use `stripe_price_id` when starting trials or subscriptions via `POST /v1/billing/subscription`. See [Multi-product billing](/platform/multi-product-billing).

***

## Error responses

Most endpoints return JSON errors:

```json theme={null}
{
  "error": "invalid request body"
}
```

| Status | Meaning                                                           |
| ------ | ----------------------------------------------------------------- |
| `401`  | Missing or invalid auth                                           |
| `403`  | Role or scope insufficient                                        |
| `404`  | Resource or feature not found                                     |
| `503`  | Dependency unavailable (Vault, inbound PAT resolution, analytics) |

***

## Related

* [API reference](/api/reference) — full endpoint tables
* [API authentication](/api/authentication)
* [Platform MCP](/api/platform-mcp)