CLI and Runtime Endpoints

User Device Auth (/api/auth)

See Auth and Error Model for headers, token types, and common error semantics.

Method	Path	Description
POST	/api/auth/device/start	create device code + user code + verification URL
POST	/api/auth/device/poll	poll device state; returns tokens when approved
POST	/api/auth/refresh	rotate user access/refresh pair
POST	/api/auth/logout	revoke user refresh token

Approval from web UI

Method	Path	Description
POST	/api/auth/device/approve	authenticated user approves device code

Runtime Auth (/api/runtime)

Method	Path	Description
POST	/api/runtime/bootstrap/exchange	exchange bootstrap token for runtime tokens
POST	/api/runtime/auth/refresh	rotate runtime access/refresh pair
POST	/api/runtime/auth/revoke	revoke runtime refresh token
GET	/api/runtime/auth/status	authenticated runtime identity/session status

Runtime Agent Control (/api/runtime)

These endpoints require runtime access tokens. Self-target operations are allowed by default. Cross-agent operations require an active delegation with matching action scope.

Method	Path	Description
POST	/api/runtime/agents/:id/start	start runtime target agent machine
POST	/api/runtime/agents/:id/stop	stop runtime target agent machine
GET	/api/runtime/agents/:id/status	read runtime target agent machine status

Runtime Updates (/api/runtime/updates)

These endpoints require runtime access tokens.

Method	Path	Description
GET	/api/runtime/updates/manifest	fetch release manifest overview
GET	/api/runtime/updates/scripts?path=<...>	fetch update script body
POST	/api/runtime/updates/check	resolve update decision for current runtime
POST	/api/runtime/updates/apply	request apply payload (requires approved=true + grant token)
POST	/api/runtime/updates/report	report applied runtime version

Related Grant Endpoint (Web/API Side)

Method	Path	Description
POST	/api/agents/:id/runtime-update-grant	issue one-time grant token used by runtime apply flow

Copy/Paste Examples

Start Device Login

curl -X POST "$ROBERTO_API_URL/api/auth/device/start" \
  -H "Content-Type: application/json" \
  -d '{"clientName":"roberto-cli"}'

Example 200 response:

{
  "deviceCode": "dev_abc123",
  "userCode": "F6H9-K2Q1",
  "verificationUri": "https://app.robertoagent.com/auth/device",
  "verificationUriComplete": "https://app.robertoagent.com/auth/device?user_code=F6H9-K2Q1",
  "expiresIn": 900,
  "interval": 5,
  "status": "pending"
}

Poll Device Login

curl -X POST "$ROBERTO_API_URL/api/auth/device/poll" \
  -H "Content-Type: application/json" \
  -d '{"deviceCode":"dev_abc123"}'

Pending response:

{
  "status": "authorization_pending",
  "interval": 5
}

Authorized response:

{
  "status": "authorized",
  "tokenType": "Bearer",
  "accessToken": "<user_access_token>",
  "accessTokenExpiresAt": "2026-02-21T12:30:00.000Z",
  "refreshToken": "<user_refresh_token>",
  "refreshTokenExpiresAt": "2026-03-22T12:00:00.000Z",
  "userId": "user_123",
  "plan": "pro"
}

Runtime Bootstrap Exchange

curl -X POST "$ROBERTO_API_URL/api/runtime/bootstrap/exchange" \
  -H "Content-Type: application/json" \
  -d '{
    "runtimeId": "runtime_123",
    "bootstrapToken": "<bootstrap_token>",
    "runtimeVersion": "2026.02.15"
  }'

Example 200 response:

{
  "tokenType": "Bearer",
  "runtimeId": "runtime_123",
  "agentId": "agent_123",
  "userId": "user_123",
  "runtimeVersion": "2026.02.15",
  "accessToken": "<runtime_access_token>",
  "accessTokenExpiresAt": "2026-02-21T12:30:00.000Z",
  "refreshToken": "<runtime_refresh_token>",
  "refreshTokenExpiresAt": "2026-03-22T12:00:00.000Z"
}

Runtime Update Check

curl -X POST "$ROBERTO_API_URL/api/runtime/updates/check" \
  -H "Authorization: Bearer $ROBERTO_RUNTIME_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currentVersion": "2026.02.15",
    "channel": "stable"
  }'

Example 200 response:

{
  "ok": true,
  "runtimeId": "runtime_123",
  "agentId": "agent_123",
  "userId": "user_123",
  "channel": "stable",
  "currentVersion": "2026.02.15",
  "targetVersion": "2026.02.20",
  "updateAvailable": true,
  "requiresApproval": true,
  "notes": "Security update",
  "scripts": [
    {
      "id": "step_1",
      "description": "Apply runtime patch",
      "path": "scripts/update-2026.02.20.sh",
      "sha256": "abc123...",
      "url": "https://api.robertoagent.com/api/runtime/updates/scripts?path=scripts%2Fupdate-2026.02.20.sh"
    }
  ]
}

Runtime Update Apply

curl -X POST "$ROBERTO_API_URL/api/runtime/updates/apply" \
  -H "Authorization: Bearer $ROBERTO_RUNTIME_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "approved": true,
    "grantToken": "rtug_abc123",
    "currentVersion": "2026.02.15",
    "channel": "stable",
    "targetVersion": "2026.02.20"
  }'

Example 200 response:

{
  "ok": true,
  "runtimeId": "runtime_123",
  "agentId": "agent_123",
  "userId": "user_123",
  "channel": "stable",
  "currentVersion": "2026.02.15",
  "targetVersion": "2026.02.20",
  "updateAvailable": true,
  "requiresApproval": true,
  "notes": "Security update",
  "scripts": [
    {
      "id": "step_1",
      "description": "Apply runtime patch",
      "path": "scripts/update-2026.02.20.sh",
      "sha256": "abc123...",
      "url": "https://api.robertoagent.com/api/runtime/updates/scripts?path=scripts%2Fupdate-2026.02.20.sh"
    }
  ],
  "approved": true,
  "canExecuteRemoteScripts": true
}