Skip to main content
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-wheelhouse-id"
}
Request (paste bearer once): 
{
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "form-leads",
  "automation_pat_id": "pat-wheelhouse-id",
  "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"

​
Workflow connection overrides

PUT /v1/workflows/{id}/connection-overrides — project_contributor (API only — no Console panel) Request: 
{
  "overrides": [
    {
      "instance_id": "mcp-instance-uuid",
      "connection_id": "connection-uuid-for-prod"
    }
  ]
}
Response (200): 
{
  "status": "ok"
}
List: 
GET /v1/workflows/{id}/connection-overrides

{
  "overrides": [
    {
      "instance_id": "mcp-instance-uuid",
      "connection_id": "connection-uuid-for-prod"
    }
  ]
}

​
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"
}
StatusMeaning
401Missing or invalid auth
403Role or scope insufficient
404Resource or feature not found
503Dependency unavailable (Vault, inbound PAT resolution, analytics)