Skip to content

Update API reference for endpoint paths and response shapes #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update API reference for endpoint paths and response shapes #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 77 additions & 32 deletions api-reference/agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@

## Delete agent

<Warning>`DELETE /api/agents/:id` is deprecated. Use the lifecycle endpoints to manage agent state (for example, [`POST /api/instance/:userId/stop`](#stop-agent)).</Warning>
<Warning>`DELETE /api/agents/:id` is deprecated. Use the lifecycle endpoints to manage agent state (for example, [`POST /api/agents/:id/stop`](#stop-agent)).</Warning>

## Provision agent

Expand Down Expand Up @@ -220,7 +220,7 @@
| 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

Expand All @@ -232,7 +232,7 @@
"timestamp": "2026-03-19T00:00:00Z",
"level": "info",
"message": "Agent started successfully",
"source": "system",
"source": "agent",
"agentId": "agent_123"
}
],
Expand Down Expand Up @@ -278,6 +278,8 @@

The `sender` field is either `user` or `agent`. The `platform` field indicates the messaging channel: `telegram`, `discord`, or `whatsapp`.

<Note>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.</Note>

## Get agent stats

```http
Expand Down Expand Up @@ -332,25 +334,25 @@

## 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
Expand All @@ -363,35 +365,44 @@
### 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.

```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.
Expand All @@ -406,7 +417,7 @@
### Reset agent memory

```http
POST /api/instance/:userId/reset-memory
POST /api/agents/:id/reset-memory
```

Returns the backend response directly.
Expand Down Expand Up @@ -435,44 +446,48 @@
| 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"
}
Expand All @@ -481,7 +496,7 @@
## 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.
Expand All @@ -501,12 +516,12 @@

## Agent verification

Agents can be verified using multiple verification types: `eas` (Ethereum Attestation Service), `coinbase`, `ens`, or `webauthn`.

Check warning on line 519 in api-reference/agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/agents.mdx#L519 

Did you really mean 'Ethereum'?

### Get verification status

```http
GET /api/agents/:id/verify
GET /api/agents/:id/verification
```

```json
Expand Down Expand Up @@ -574,7 +589,7 @@

Provisions a new agent with messaging channel tokens. No authentication is required. Rate-limited per IP. At least one channel token is required.

The request is proxied to the backend provisioning service. A dedicated Mux live stream is automatically created for the agent.

Check warning on line 592 in api-reference/agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/agents.mdx#L592 

Did you really mean 'proxied'?

Check warning on line 592 in api-reference/agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/agents.mdx#L592 

Did you really mean 'Mux'?

### Request body

Expand All @@ -596,12 +611,42 @@
{
"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

Expand Down
40 changes: 38 additions & 2 deletions api-reference/ai.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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 |
Expand Down Expand Up @@ -99,6 +120,12 @@ GET /api/ai/models/:provider
}
```

### Errors

| Code | Description |
|------|-------------|
| 500 | Failed to fetch models for provider |

## Select model

```http
Expand All @@ -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"
Expand All @@ -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

Expand Down Expand Up @@ -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 |
2 changes: 1 addition & 1 deletion api-reference/gateway.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

# Gateway

The v1 gateway routes incoming requests to registered plugins. It supports dual payment methods — Stripe (existing) and [MPP](/payments/mpp) (Machine Payments Protocol) via the Tempo blockchain.

Check warning on line 8 in api-reference/gateway.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/gateway.mdx#L8 

Did you really mean 'blockchain'?

## Base URL

Expand Down Expand Up @@ -137,7 +137,7 @@

## 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

Expand Down
1 change: 1 addition & 0 deletions api-reference/keys.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

# API keys

Create and manage API keys for authenticating with the Agentbot API. All endpoints require session authentication.

Check warning on line 8 in api-reference/keys.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/keys.mdx#L8 

Did you really mean 'Agentbot'?

## List keys

Expand Down Expand Up @@ -111,3 +111,4 @@
|------|-------------|
| 401 | Unauthorized |
| 404 | Key not found |
| 500 | Internal server error |
23 changes: 12 additions & 11 deletions api-reference/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
title: API reference
description: "Complete API reference for Agentbot"

Check warning on line 3 in api-reference/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/overview.mdx#L3 

Did you really mean 'Agentbot'?
---

# API reference

Complete API reference for Agentbot.

Check warning on line 8 in api-reference/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/overview.mdx#L8 

Did you really mean 'Agentbot'?

## Base URL

Expand All @@ -15,7 +15,7 @@

## Authentication

Agentbot supports two authentication methods depending on the endpoint.

Check warning on line 18 in api-reference/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/overview.mdx#L18 

Did you really mean 'Agentbot'?

### Session authentication

Expand All @@ -39,7 +39,7 @@
| `/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 |
Expand Down Expand Up @@ -93,18 +93,18 @@
| `/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 |
Expand Down Expand Up @@ -142,14 +142,15 @@
| `/api/auth/callback/wallet` | POST | Wallet sign in (SIWE) |
| `/api/auth/forgot-password` | POST | Request password reset |
| `/api/auth/reset-password` | POST | Reset password |
| `/api/auth/farcaster/verify` | GET, POST | Verify Farcaster identity (GET returns endpoint metadata) |

Check warning on line 145 in api-reference/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/overview.mdx#L145 

Did you really mean 'Farcaster'?
| `/api/auth/farcaster/refresh` | GET, POST | Refresh Farcaster token (GET returns endpoint metadata) |

Check warning on line 146 in api-reference/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/overview.mdx#L146 

Did you really mean 'Farcaster'?
| `/api/auth/token-gating/verify` | GET, POST | Verify token gating access |
| `/api/billing` | GET | Get billing info |
| `/api/billing` | POST | Billing actions (`create-checkout`, `enable-byok`, `disable-byok`, `get-usage`, `buy-credits`) |
| `/api/stripe/checkout` | GET | Redirect to Stripe checkout (accepts `plan` query param: `solo`, `collective`, `label`, `network`) |

Check warning on line 150 in api-reference/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/overview.mdx#L150 

Did you really mean 'param'?
| `/api/stripe/credits` | GET | Redirect to Stripe credit purchase (accepts `price` query param) |

Check warning on line 151 in api-reference/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/overview.mdx#L151 

Did you really mean '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) |
Expand All @@ -162,7 +163,7 @@

## SDK

Use the Agentbot SDK:

Check warning on line 166 in api-reference/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/overview.mdx#L166 

Did you really mean 'Agentbot'?

```bash
npm install @agentbot/sdk
Expand Down
Loading