Web Client Endpoints

All endpoints are under /api/* and use bearer auth for protected user routes. See Auth and Error Model for auth headers and common non-200 behavior.

Agents

Method	Path	Used for
GET	/api/agents	list agents
POST	/api/agents	create agent
GET	/api/agents/:id	fetch agent detail
PATCH	/api/agents/:id	update agent fields
DELETE	/api/agents/:id	delete agent
POST	/api/agents/:id/provision	provision runtime machine
POST	/api/agents/:id/clone	clone existing agent
POST	/api/agents/:id/start	start machine
POST	/api/agents/:id/stop	stop machine
GET	/api/agents/:id/status	read machine state
GET	/api/agents/:id/gateway-access	obtain gateway token/url
GET	/api/agents/:id/runtime-update-status	runtime update decision/status
POST	/api/agents/:id/runtime-update-grant	issue one-time update grant
POST	/api/agents/:id/connect-telegram	connect Telegram channel
POST	/api/agents/:id/whatsapp-qr	generate/retrieve WhatsApp QR
POST	/api/agents/:id/whatsapp-wait	wait for WhatsApp connect completion

User Profile

Method	Path	Used for
GET	/api/users/me	load profile
PATCH	/api/users/me	update profile name/email

Billing

Method	Path	Used for
GET	/api/billing/summary	current customer/subscription/entitlement snapshot
GET	/api/billing/usage-summary	usage rollup and percentiles
POST	/api/billing/checkout	open subscription checkout
POST	/api/billing/credits/checkout	buy prepaid credits
POST	/api/billing/portal	open billing portal
POST	/api/billing/sync	force billing sync when billing state appears out of date
GET	/api/billing/runtime-requests	list runtime spend approval requests
GET	/api/billing/runtime-requests/:id	get one runtime spend request
POST	/api/billing/runtime-requests/:id/approve	approve runtime spend request
POST	/api/billing/runtime-requests/:id/deny	deny runtime spend request
GET	/api/billing/runtime-spend-policies/:controllerAgentId	get controller spend policy
POST	/api/billing/runtime-spend-policies/:controllerAgentId	create/update controller spend policy
DELETE	/api/billing/runtime-spend-policies/:controllerAgentId	revoke controller spend policy
GET	/api/runtime/identities	list owned runtime identities for delegation/update selection
GET	/api/runtime/delegations	list runtime delegation grants
POST	/api/runtime/delegations	create runtime delegation grant
DELETE	/api/runtime/delegations/:id	revoke runtime delegation grant

Checkout semantics:

• Web plan changes use checkout session creation for both upgrades and downgrades.
• The web app does not call a direct PATCH plan endpoint.
• Success/cancel is handled by redirecting back to /settings with:
  • billing=success|cancel for subscription checkout.
  • billing=credits_success|credits_cancel for one-time credits checkout.

Device Approval UI

Method	Path	Used for
POST	/api/auth/device/approve	approve CLI/MCP device code from browser

Copy/Paste Examples

Create an Agent

curl -X POST "$ROBERTO_API_URL/api/agents" \
  -H "Authorization: Bearer $ROBERTO_USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Copilot",
    "persona": "Helpful support specialist",
    "plan": "pro"
  }'

Example 201 response:

{
  "id": "agent_123",
  "userId": "user_123",
  "name": "Support Copilot",
  "persona": "Helpful support specialist",
  "avatar": "",
  "status": "offline",
  "plan": "pro",
  "flyAppName": null,
  "flyMachineId": null,
  "flyVolumeId": null,
  "gatewayUrl": null,
  "channels": {},
  "capabilities": {},
  "usageMessages": 0,
  "usageTokensUsed": 0,
  "createdAt": "2026-02-21T00:00:00.000Z",
  "updatedAt": "2026-02-21T00:00:00.000Z"
}

Issue Runtime Update Grant

curl -X POST "$ROBERTO_API_URL/api/agents/$AGENT_ID/runtime-update-grant" \
  -H "Authorization: Bearer $ROBERTO_USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "stable",
    "currentVersion": "2026.02.15"
  }'

Example 200 response:

{
  "ok": true,
  "agentId": "agent_123",
  "runtimeId": "runtime_123",
  "channel": "stable",
  "currentVersion": "2026.02.15",
  "currentVersionSource": "runtime_identity",
  "targetVersion": "2026.02.20",
  "grantToken": "rtug_abc123",
  "expiresAt": "2026-02-21T12:10:00.000Z",
  "applyCommand": "roberto auth runtime-apply-update --approve --grant-token rtug_abc123 --target-version 2026.02.20"
}

Read Billing Summary

curl "$ROBERTO_API_URL/api/billing/summary" \
  -H "Authorization: Bearer $ROBERTO_USER_ACCESS_TOKEN"

Example 200 response:

{
  "customer": {
    "stripeCustomerId": "cus_123",
    "defaultPaymentMethodId": "pm_123"
  },
  "subscription": {
    "stripeSubscriptionId": "sub_123",
    "stripePriceId": "price_123",
    "billingMode": "standard_stripe",
    "status": "active",
    "currentPeriodStart": "2026-02-01T00:00:00.000Z",
    "currentPeriodEnd": "2026-03-01T00:00:00.000Z",
    "cancelAtPeriodEnd": false
  },
  "entitlement": {
    "planCode": "pro",
    "maxAgents": 3,
    "includedMessages": 10000,
    "includedTokens": 0,
    "includedSearchRequestsWeekly": 2500,
    "allowProvisioning": true,
    "allowStartStop": true,
    "updatedAt": "2026-02-21T00:00:00.000Z"
  },
  "credits": {
    "balanceUnits": 125,
    "updatedAt": "2026-02-21T00:00:00.000Z"
  }
}

List Runtime Spend Requests

curl "$ROBERTO_API_URL/api/billing/runtime-requests?status=pending&limit=25" \
  -H "Authorization: Bearer $ROBERTO_USER_ACCESS_TOKEN"

Example 200 response:

{
  "requests": [
    {
      "id": "rsr_123",
      "ownerUserId": "user_123",
      "controllerAgentId": "agent_controller",
      "targetAgentId": "agent_target",
      "policyId": "rsp_123",
      "actionType": "credits_increase",
      "requestedUnits": 100,
      "status": "pending",
      "requestedByRuntimeId": "runtime_123",
      "approvedByUserId": null,
      "approvalMode": null,
      "reason": "Need additional credits for escalation workflow",
      "metadata": {},
      "expiresAt": "2026-02-21T14:00:00.000Z",
      "decidedAt": null,
      "createdAt": "2026-02-21T13:00:00.000Z",
      "updatedAt": "2026-02-21T13:00:00.000Z"
    }
  ]
}

Upsert Runtime Spend Policy

curl -X POST "$ROBERTO_API_URL/api/billing/runtime-spend-policies/$CONTROLLER_AGENT_ID" \
  -H "Authorization: Bearer $ROBERTO_USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "maxSingleUnits": 200,
    "maxDailyUnits": 2000,
    "maxMonthlyUnits": 10000,
    "allowedActionTypes": ["credits_increase"]
  }'

Example 200 response:

{
  "ok": true,
  "policy": {
    "id": "rsp_123",
    "ownerUserId": "user_123",
    "controllerAgentId": "agent_controller",
    "enabled": true,
    "maxSingleUnits": 200,
    "maxDailyUnits": 2000,
    "maxMonthlyUnits": 10000,
    "allowedActionTypes": ["credits_increase"],
    "expiresAt": null,
    "createdByUserId": "user_123",
    "revokedAt": null,
    "createdAt": "2026-02-21T13:00:00.000Z",
    "updatedAt": "2026-02-21T13:00:00.000Z"
  }
}

List Runtime Identities

curl "$ROBERTO_API_URL/api/runtime/identities?includeRevoked=false&limit=50" \
  -H "Authorization: Bearer $ROBERTO_USER_ACCESS_TOKEN"

Example 200 response:

{
  "identities": [
    {
      "id": "runtime_123",
      "agentId": "agent_controller",
      "status": "active",
      "runtimeReleaseVersion": "2026.02.21",
      "revokedAt": null,
      "createdAt": "2026-02-20T10:00:00.000Z",
      "updatedAt": "2026-02-21T14:45:00.000Z",
      "isActive": true
    }
  ]
}

Create Runtime Delegation

curl -X POST "$ROBERTO_API_URL/api/runtime/delegations" \
  -H "Authorization: Bearer $ROBERTO_USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "runtimeId": "runtime_123",
    "ttlSeconds": 600,
    "scope": {
      "actions": ["runtime:billing:credits_increase"],
      "targetAgentIds": ["agent_target"]
    }
  }'

Example 201 response:

{
  "ok": true,
  "delegation": {
    "id": "rdg_123",
    "runtimeId": "runtime_123",
    "issuedByUserId": "user_123",
    "scope": {
      "actions": ["runtime:billing:credits_increase"],
      "targetAgentIds": ["agent_target"]
    },
    "expiresAt": "2026-02-21T15:00:00.000Z",
    "revokedAt": null,
    "createdAt": "2026-02-21T14:50:00.000Z",
    "isActive": true
  }
}