From 2bc48a0369ee6c1deed0661d9e3be11d624f898f Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 20 Mar 2026 21:14:21 +0000 Subject: [PATCH] Update API docs to match current endpoint paths, response shapes, and error codes Generated-By: mintlify-agent --- api-reference/agents.mdx | 109 ++++++++++++++++++++++++++----------- api-reference/ai.mdx | 40 +++++++++++++- api-reference/gateway.mdx | 2 +- api-reference/keys.mdx | 1 + api-reference/overview.mdx | 23 ++++---- api-reference/wallet.mdx | 11 +++- 6 files changed, 138 insertions(+), 48 deletions(-) diff --git a/api-reference/agents.mdx b/api-reference/agents.mdx index a3b58b7..0a11f87 100644 --- a/api-reference/agents.mdx +++ b/api-reference/agents.mdx @@ -82,7 +82,7 @@ Requires authentication and ownership of the agent. ## Delete agent -`DELETE /api/agents/:id` is deprecated. Use the lifecycle endpoints to manage agent state (for example, [`POST /api/instance/:userId/stop`](#stop-agent)). +`DELETE /api/agents/:id` is deprecated. Use the lifecycle endpoints to manage agent state (for example, [`POST /api/agents/:id/stop`](#stop-agent)). ## Provision agent @@ -220,7 +220,7 @@ Requires authentication and ownership of the agent. | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `limit` | integer | 50 | Max log entries to return (max 100) | -| `level` | string | — | Filter by log level (for example, `info`, `error`, `warn`) | +| `level` | string | — | Filter by log level (for example, `info`, `error`, `warning`, `debug`) | ### Response @@ -232,7 +232,7 @@ Requires authentication and ownership of the agent. "timestamp": "2026-03-19T00:00:00Z", "level": "info", "message": "Agent started successfully", - "source": "system", + "source": "agent", "agentId": "agent_123" } ], @@ -278,6 +278,8 @@ GET /api/agents/:id/messages The `sender` field is either `user` or `agent`. The `platform` field indicates the messaging channel: `telegram`, `discord`, or `whatsapp`. +The `total` field represents the current offset plus the number of messages returned, not the absolute total message count. Use it as a cursor for pagination. + ## Get agent stats ```http @@ -332,25 +334,25 @@ When the backend is unavailable, mock data is returned with `"status": "mock"`: ## Agent lifecycle -Lifecycle operations use the `/api/instance/:userId` endpoint pattern. These endpoints require session authentication and proxy to the backend agent management service. +Lifecycle operations use the `/api/agents/:id` endpoint pattern on the backend service. The web application proxies these requests via `/api/instance/:userId` routes, which forward to the backend. These endpoints require session authentication. ### Start agent ```http -POST /api/instance/:userId/start +POST /api/agents/:id/start ``` ```json { "success": true, - "status": "running" + "status": "active" } ``` ### Stop agent ```http -POST /api/instance/:userId/stop +POST /api/agents/:id/stop ``` ```json @@ -363,20 +365,25 @@ POST /api/instance/:userId/stop ### Restart agent ```http -POST /api/instance/:userId/restart +POST /api/agents/:id/restart ``` ```json { "success": true, - "status": "running" + "status": "active", + "healedLegacyModel": false, + "healMessage": null, + "openclawVersion": "2026.3.13" } ``` +The `healedLegacyModel` field indicates whether a legacy model was automatically migrated during the restart. When `true`, `healMessage` contains a description of the migration. + ### Update agent image ```http -POST /api/instance/:userId/update +POST /api/agents/:id/update ``` Triggers an image update on the backend. @@ -384,14 +391,18 @@ Triggers an image update on the backend. ```json { "success": true, - "status": "running" + "status": "active", + "image": "agentbot:2026.3.13", + "previousImage": "agentbot:2026.3.12", + "backupPath": "/backups/agent_123_1710806400", + "openclawVersion": "2026.3.13" } ``` ### Repair agent ```http -POST /api/instance/:userId/repair +POST /api/agents/:id/repair ``` Returns the backend response directly. @@ -406,7 +417,7 @@ Returns the backend response directly. ### Reset agent memory ```http -POST /api/instance/:userId/reset-memory +POST /api/agents/:id/reset-memory ``` Returns the backend response directly. @@ -435,44 +446,48 @@ All lifecycle endpoints return the following shape on failure: | 502 | Backend service unavailable | | 500 | Internal server error | -## Get instance details +## Get agent details (backend) ```http -GET /api/instance/:userId +GET /api/agents/:id ``` -Returns the current status and metadata for an agent instance. +Returns the current status and metadata for an agent from the backend service. ### Response ```json { - "userId": "user_123", - "status": "running", + "id": "agent_123", + "status": "active", "startedAt": "2026-03-01T00:00:00Z", - "subdomain": "user_123.agents.localhost", - "url": "https://user_123.agents.localhost", + "subdomain": "agent_123.agents.localhost", + "url": "https://agent_123.agents.localhost", "plan": "free", - "openclawVersion": "2026.2.17" + "openclawVersion": "2026.3.13", + "verified": false, + "verificationType": null, + "attestationUid": null, + "verifiedAt": null } ``` -## Get instance stats +## Get agent stats (backend) ```http -GET /api/instance/:userId/stats +GET /api/agents/:id/stats ``` -Returns resource usage statistics for an agent instance. +Returns resource usage statistics for an agent from the backend service. ### Response ```json { - "userId": "user_123", + "id": "agent_123", "cpu": "0.15%", "memory": "128MiB", - "status": "running", + "status": "active", "plan": "starter", "openclawVersion": "2026.3.13" } @@ -481,7 +496,7 @@ Returns resource usage statistics for an agent instance. ## Get agent gateway token ```http -GET /api/instance/:userId/token +GET /api/agents/:id/token ``` Returns an auto-generated gateway token for the agent. A new token is created if none exists. @@ -506,7 +521,7 @@ Agents can be verified using multiple verification types: `eas` (Ethereum Attest ### Get verification status ```http -GET /api/agents/:id/verify +GET /api/agents/:id/verification ``` ```json @@ -596,12 +611,42 @@ The request is proxied to the backend provisioning service. A dedicated Mux live { "success": true, "userId": "a1b2c3d4e5", + "agentId": "agent_789", + "id": "agent_789", + "telegramToken": "***", + "discordToken": null, + "whatsappToken": null, + "aiProvider": "openrouter", + "aiProviderConfig": {}, + "plan": "free", + "streamKey": "sk-ab12-cd34-ef56", + "liveStreamId": "x7k9m2p4q1", + "rtmpServer": "rtmps://global-live.mux.com:443/app", + "playbackUrl": "https://stream.mux.com/abc123.m3u8", "subdomain": "dj-a1b2c3d4e5.agentbot.raveculture.xyz", "url": "https://dj-a1b2c3d4e5.agentbot.raveculture.xyz", - "streamKey": "sk-ab12-cd34-ef56", - "liveStreamId": "x7k9m2p4q1" -} -``` + "hls": "https://stream.mux.com/abc123.m3u8", + "rtmp": "rtmps://global-live.mux.com:443/app/sk-ab12-cd34-ef56", + "status": "active", + "createdAt": "2026-03-19T00:00:00Z", + "metadata": {} +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `agentId` | string | Unique agent identifier | +| `id` | string | Alias for `agentId` | +| `aiProvider` | string | AI provider used by the agent | +| `aiProviderConfig` | object | Provider-specific configuration | +| `plan` | string | Plan tier assigned to the agent | +| `rtmpServer` | string | RTMP server URL for live streaming | +| `playbackUrl` | string | HLS playback URL for the live stream | +| `hls` | string | HLS stream URL | +| `rtmp` | string | Full RTMP ingest URL including stream key | +| `status` | string | Agent status after provisioning | +| `createdAt` | string | ISO 8601 creation timestamp | +| `metadata` | object | Additional metadata from the provisioning service | ### Errors diff --git a/api-reference/ai.mdx b/api-reference/ai.mdx index 36bb37d..0007d3c 100644 --- a/api-reference/ai.mdx +++ b/api-reference/ai.mdx @@ -61,7 +61,14 @@ Returns all available AI models across providers. "models": [ { "id": "anthropic/claude-sonnet-4-20250514", - "provider": "openrouter" + "name": "Claude Sonnet", + "provider": "openrouter", + "description": "Fast, intelligent model for everyday tasks", + "tags": ["general", "coding"], + "inputCost": 3.0, + "outputCost": 15.0, + "contextWindow": 200000, + "available": true } ], "count": 1, @@ -70,6 +77,20 @@ Returns all available AI models across providers. } ``` +Each model object includes: + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Model identifier | +| `name` | string | Human-readable model name | +| `provider` | string | Provider serving the model | +| `description` | string | Short description of the model | +| `tags` | string[] | Task categories the model is suited for | +| `inputCost` | number | Cost per million input tokens (USD) | +| `outputCost` | number | Cost per million output tokens (USD) | +| `contextWindow` | number | Maximum context length in tokens | +| `available` | boolean | Whether the model is currently available | + ### Errors | Code | Description | @@ -99,6 +120,12 @@ GET /api/ai/models/:provider } ``` +### Errors + +| Code | Description | +|------|-------------| +| 500 | Failed to fetch models for provider | + ## Select model ```http @@ -119,7 +146,14 @@ Automatically selects the best model for a given task type. { "model": { "id": "anthropic/claude-sonnet-4-20250514", - "provider": "openrouter" + "name": "Claude Sonnet", + "provider": "openrouter", + "description": "Fast, intelligent model for everyday tasks", + "tags": ["general", "coding"], + "inputCost": 3.0, + "outputCost": 15.0, + "contextWindow": 200000, + "available": true }, "taskType": "general", "timestamp": "2026-03-19T00:00:00Z" @@ -131,6 +165,7 @@ Automatically selects the best model for a given task type. | Code | Description | |------|-------------| | 404 | No models available | +| 500 | Internal server error | ## Chat completion @@ -210,3 +245,4 @@ Estimate the cost of a request based on token counts and model pricing. | Code | Description | |------|-------------| | 400 | Model, inputTokens, and outputTokens are all required | +| 500 | Internal server error | diff --git a/api-reference/gateway.mdx b/api-reference/gateway.mdx index 082887a..c98255d 100644 --- a/api-reference/gateway.mdx +++ b/api-reference/gateway.mdx @@ -137,7 +137,7 @@ When paid via MPP, the response includes a `Payment-Receipt` header and the `pay ## CORS -The gateway supports CORS preflight via `OPTIONS /api/v1/gateway`. Allowed methods are `GET`, `POST`, and `OPTIONS`. The `Authorization`, `Content-Type`, `X-Plugin-Id`, and `X-Payment-Method` headers are permitted. +The gateway supports CORS preflight via `OPTIONS /api/v1/gateway`. Allowed methods are `POST` and `OPTIONS`. The `Authorization`, `Content-Type`, `X-Plugin-Id`, and `X-Payment-Method` headers are permitted. ## Rate limits diff --git a/api-reference/keys.mdx b/api-reference/keys.mdx index 924e083..506faca 100644 --- a/api-reference/keys.mdx +++ b/api-reference/keys.mdx @@ -111,3 +111,4 @@ Requires ownership of the key. |------|-------------| | 401 | Unauthorized | | 404 | Key not found | +| 500 | Internal server error | diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx index cb525ba..e62860d 100644 --- a/api-reference/overview.mdx +++ b/api-reference/overview.mdx @@ -39,7 +39,7 @@ API keys use the `sk_` prefix and are shown only once at creation time. See the | `/api/v1/gateway` | 100/min | | `/api/agents` | 100/min | | `/api/chat` | 60/min | -| `/api/instance` | 30/min | +| `/api/agents/:id/*` | 30/min | | `/api/provision` | Rate-limited per IP | | `/api/register` | Rate-limited per IP | | `/api/auth/forgot-password` | Rate-limited per IP | @@ -93,18 +93,18 @@ API keys use the `sk_` prefix and are shown only once at creation time. See the | `/api/agents/:id/config` | PUT | Update agent configuration | | `/api/agents/:id/messages` | GET | Get agent messages | | `/api/agents/:id/stats` | GET | Get agent stats | -| `/api/agents/:id/verify` | GET | Get verification status | +| `/api/agents/:id/verification` | GET | Get verification status | | `/api/agents/:id/verify` | POST | Verify an agent | | `/api/agents/:id/verify` | DELETE | Remove verification | -| `/api/instance/:userId` | GET | Get instance details | -| `/api/instance/:userId/start` | POST | Start an agent | -| `/api/instance/:userId/stop` | POST | Stop an agent | -| `/api/instance/:userId/restart` | POST | Restart an agent | -| `/api/instance/:userId/update` | POST | Update agent image | -| `/api/instance/:userId/repair` | POST | Repair an agent | -| `/api/instance/:userId/reset-memory` | POST | Reset agent memory | -| `/api/instance/:userId/token` | GET | Get agent gateway token | -| `/api/instance/:userId/stats` | GET | Get instance stats | +| `/api/agents/:id` | GET | Get agent details (backend) | +| `/api/agents/:id/start` | POST | Start an agent | +| `/api/agents/:id/stop` | POST | Stop an agent | +| `/api/agents/:id/restart` | POST | Restart an agent | +| `/api/agents/:id/update` | POST | Update agent image | +| `/api/agents/:id/repair` | POST | Repair an agent | +| `/api/agents/:id/reset-memory` | POST | Reset agent memory | +| `/api/agents/:id/token` | GET | Get agent gateway token | +| `/api/agents/:id/stats` | GET | Get agent stats (backend) | | `/api/agents/provision` | POST | Provision a new agent | | `/api/agents/provision` | GET | List provisioned agents | | `/api/chat` | GET | List message history | @@ -150,6 +150,7 @@ API keys use the `sk_` prefix and are shown only once at creation time. See the | `/api/stripe/checkout` | GET | Redirect to Stripe checkout (accepts `plan` query param: `solo`, `collective`, `label`, `network`) | | `/api/stripe/credits` | GET | Redirect to Stripe credit purchase (accepts `price` query param) | | `/api/stripe/storage-upgrade` | POST | Upgrade storage plan | +| `/health` | GET | Health check (backend only, no `/api` prefix) | | `/api/metrics/:userId/historical` | GET | Get historical time-series metrics (backend only) | | `/api/metrics/:userId/performance` | GET | Get current performance metrics (backend only) | | `/api/metrics/:userId/summary` | GET | Get music industry metrics summary (backend only) | diff --git a/api-reference/wallet.mdx b/api-reference/wallet.mdx index 81437e3..56e8b7a 100644 --- a/api-reference/wallet.mdx +++ b/api-reference/wallet.mdx @@ -90,7 +90,14 @@ Creates a new wallet for the authenticated user. } ``` -Returns `400` if a wallet already exists. +Returns `400` if a wallet already exists. The error response includes the existing wallet address: + +```json +{ + "error": "Wallet already exists", + "address": "0x..." +} +``` ### Action: `get_seed` @@ -193,7 +200,7 @@ Creates a new wallet using the Coinbase Developer Platform SDK. | Code | Description | |------|-------------| | 400 | Email required | -| 500 | CDP not configured (set `CDP_PROJECT_ID` in environment) | +| 500 | CDP not configured. Response includes `error` and `setup` fields: `{ "error": "CDP not configured", "setup": "Set CDP_PROJECT_ID in environment" }` | ## CDP wallet status