API examples

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:

export AR_API="https://api.agentruntime.io"
export AR_TOKEN="pat_…"
export AR_TENANT="your-workspace-slug"
export AR_PROJECT="your-project-id"

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 for PAT scopes and session cookies.

Create a workflow

POST /v1/workflows — project_contributor Request:

{
  "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):

{
  "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:

{
  "changelog": "Initial publish"
}

Response (201):

{
  "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:

{
  "command": "start",
  "params": {
    "customer_email": "alex@example.com",
    "order_id": "12345"
  }
}

Response (200):

{
  "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

{ "command": "pause", "params": { "run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }

{ "command": "resume", "params": { "run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }

{ "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):

{
  "approved": true
}

Approve with custom result fields:

{
  "approved": true,
  "result": {
    "comment_body": "Edited review text posted to GitHub"
  }
}

Response (200):

{
  "status": "completed",
  "task_id": "approve-review",
  "approved": true
}

See Human tasks.

Create inbound webhook subscription

POST /v1/inbound-webhooks — project_contributor Request (Vault-backed PAT id):

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

Request (paste bearer once):

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

Response (201):

{
  "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)

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:

{
  "display_name": "GitHub CI",
  "provider": "custom",
  "service": "api_key",
  "credentials": {
    "api_key": "ghp_…"
  }
}

Response (201):

{
  "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:

{
  "name": "Internal tools",
  "canonical_url": "https://tools.example.com/mcp",
  "mode": "third_party",
  "auth_mode": "token"
}

Response (201):

{
  "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.

Create a PAT

POST /v1/pats — project_contributor Request:

{
  "display_name": "CI deploy",
  "scopes": ["workflow:read", "workflow:run"]
}

Response (201):

{
  "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):

{
  "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.

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):

{
  "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.

Error responses

Most endpoints return JSON errors:

{
  "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)

API reference — full endpoint tables
API authentication
Platform MCP

Get started

Platform

Workflows

Guides

Integration setup

Connectors

AI & chat

API

Create a workflow

Publish a version

Start a run

Pause, resume, stop

Complete a human task

Create inbound webhook subscription

Public ingress (external sender)

Create a custom connection

Register a custom MCP server

Create a PAT

Billing usage snapshot

Plan catalog (product-scoped)

Error responses

​Create a workflow

​Publish a version

​Start a run

​Pause, resume, stop

​Complete a human task

​Create inbound webhook subscription

​Public ingress (external sender)

​Create a custom connection

​Register a custom MCP server

​Create a PAT

​Billing usage snapshot

​Plan catalog (product-scoped)

​Error responses

​Related

Create a workflow

Publish a version

Start a run

Pause, resume, stop

Complete a human task

Create inbound webhook subscription

Public ingress (external sender)

Create a custom connection

Register a custom MCP server

Create a PAT

Billing usage snapshot

Plan catalog (product-scoped)

Error responses

Related