Skip to content

Align API docs with current endpoint behavior #352

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

Align API docs with current endpoint behavior #352

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
8 changes: 4 additions & 4 deletions api-reference/agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,19 @@ description: "Create, manage, and interact with agents"

Create, manage, and interact with agents.

<Note>All agent endpoints that require authentication are scoped to the authenticated user's data through [row-level security](/security#row-level-security). You can only access agents that belong to your account.</Note>
<Note>Agent endpoints accessed through the web proxy are scoped to the authenticated user's data. The backend agent list endpoint (`GET /api/agents`) does not apply user-scoping — it returns all containers on the host. Single-agent endpoints on the backend enforce ownership via an `ownerEmail` check when available.</Note>

## List agents

```http
GET /api/agents
```

Returns all agents owned by the authenticated user. When no session is present, returns an empty list instead of a `401` error.
Returns agents visible to the caller. The backend and web proxy have different scoping behavior — see the notes below.

### Response (backend)

The backend returns a flat array of agent objects:
The backend lists all agent containers on the host by querying Docker directly. No authentication or user-scoping is applied — the response includes every container whose name matches the `openclaw-` prefix. When no containers exist, an empty array is returned.

```json
[
Expand Down Expand Up @@ -76,7 +76,7 @@ The web proxy wraps the response in an object:
| `count` | number | Total number of agents returned |
| `status` | string | Response status (`ok`) |

<Note>The backend and web proxy return different response shapes. The backend returns a flat array with `created`, `subdomain`, and `url` fields. The web proxy wraps the data in an `agents` key and includes `name`, `model`, `websocketUrl`, `createdAt`, and `updatedAt` fields.</Note>
<Note>The backend and web proxy return different response shapes and scoping. The backend returns a flat array of all containers on the host (not user-scoped) with `created`, `subdomain`, and `url` fields. The web proxy wraps the data in an `agents` key, scopes results to the authenticated user, and includes `name`, `model`, `websocketUrl`, `createdAt`, and `updatedAt` fields.</Note>

## Create agent

Expand Down
56 changes: 56 additions & 0 deletions api-reference/ai.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,62 @@ Endpoints for interacting with AI models through a unified provider layer. These

<Warning>All `/api/ai/*` endpoints share a rate limit of 30 requests per minute per IP, not just the chat endpoint.</Warning>

## List models (web)

```http
GET /api/models
```

No authentication required. Returns available AI models from OpenRouter, sorted by price with featured models listed first. Free-tier models (`:free` suffix) are excluded.

### Response

```json
{
"models": [
{
"id": "moonshot/kimi-k2.5-thinking",
"name": "Kimi K2.5 Thinking",
"contextLength": 128000,
"pricing": {
"prompt": 0.000003,
"completion": 0.000012
},
"featured": true,
"description": "Advanced reasoning model with thinking capabilities"
},
{
"id": "anthropic/claude-sonnet-4-20250514",
"name": "Claude Sonnet 4",
"contextLength": 200000,
"pricing": {
"prompt": 0.003,
"completion": 0.015
}
}
]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `models` | array | List of model objects sorted by featured status then price ascending |
| `models[].id` | string | Model identifier |
| `models[].name` | string | Human-readable model name |
| `models[].contextLength` | number | Maximum context window in tokens |
| `models[].pricing.prompt` | number | Cost per prompt token |
| `models[].pricing.completion` | number | Cost per completion token |
| `models[].featured` | boolean | Present on featured models. Featured models are sorted first. |
| `models[].description` | string | Present on featured models. Short description of the model. |

<Note>This is the web-facing endpoint for client model lists. It fetches models from OpenRouter at request time. The backend provides a separate [model listing endpoint](#list-models) with additional fields like `provider`, `tags`, and `available`.</Note>

### Errors

| Code | Description |
|------|-------------|
| 500 | Failed to fetch models — upstream OpenRouter API error or invalid response |

## Health check

```http
Expand Down
7 changes: 3 additions & 4 deletions api-reference/orchestration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ Submit a batch of tool calls for concurrent execution. The system automatically
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tools` | array | Yes | Array of tool call objects to execute. Minimum 1, maximum 20. |
| `tools[].id` | string | Yes | Unique identifier for this tool call |
| `tools[].toolName` | string | Yes | Name of the tool to invoke (for example, `read`, `grep`, `write`, `bash`) |
| `tools[].id` | string | No | Identifier for this tool call. Used to correlate results. |
| `tools[].toolName` | string | No | Name of the tool to invoke (for example, `read`, `grep`, `write`, `bash`) |
| `tools[].input` | object | Yes | Input parameters for the tool call |
| `userId` | string | No | User identifier for server-side logging. When calling through the Next.js proxy, this field is automatically populated from your session and does not need to be sent by the client. |

Expand Down Expand Up @@ -119,12 +119,11 @@ In this example, `t1` and `t2` are read-only and run in parallel. `t3` is mutati
|------|-------------|
| 400 | `tools array required` — missing or empty `tools` field |
| 400 | `Maximum 20 tools per batch` — batch size exceeds the limit |
| 400 | `Each tool must have id and toolName` — a tool object is missing `id` or `toolName` |
| 401 | Unauthorized — missing bearer token |
| 403 | Forbidden — invalid bearer token |
| 500 | Internal server error |

<Note>Each tool object in the array must include both `id` and `toolName`. The API validates these fields and returns a `400` error if any tool object is missing either field.</Note>
<Note>The batch endpoint validates that the `tools` array is present, non-empty, and does not exceed 20 items. Individual tool objects are not validated at the request level — missing fields may cause errors during execution.</Note>

### Serial failure behavior

Expand Down
43 changes: 43 additions & 0 deletions api-reference/referrals.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,3 +52,46 @@ Requires session authentication. Returns the authenticated user's referral code,
| 500 | Failed to fetch referrals |

<Note>Referral credits are also included in the [dashboard data](/api-reference/usage-tracking#dashboard-data) and [dashboard bootstrap](/api-reference/usage-tracking#dashboard-bootstrap) responses. Use this endpoint when you need the full referral breakdown including conversion statistics.</Note>

## Get credit balance

```http
GET /api/credits
```

Requires session authentication. Returns the authenticated user's credit balance, referral code, referral count, and current plan.

### Response

```json
{
"credits": 30,
"referralCode": "abc123",
"referralCount": 3,
"plan": "solo"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `credits` | number | Accumulated referral credits balance. |
| `referralCode` | string \| null | Your referral code, or `null` if not set. |
| `referralCount` | number | Number of users referred. |
| `plan` | string | Current subscription plan. |

When the user is not found in the database, the endpoint returns a zero-balance fallback without the `plan` field:

```json
{
"credits": 0,
"referralCode": null,
"referralCount": 0
}
```

### Errors

| Code | Description |
|------|-------------|
| 401 | Unauthorized — no valid session |
| 500 | Returns `{ "credits": 0 }` on internal errors |
4 changes: 3 additions & 1 deletion api-reference/registration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,11 +191,13 @@ Returns registered installations belonging to the authenticated user. Results ar

## Get registration token (internal)

<Warning>**Not yet available.** This endpoint is planned but not currently implemented in the backend registration router. The specification below describes the intended behavior for a future release.</Warning>

```http
GET /api/registration/token
```

Returns the gateway token for a user from the agent registrations table. This is an internal API used by the Edge Runtime dashboard to retrieve gateway tokens without direct database access from edge functions.
Returns the gateway token for a user from the agent registrations table. This is an internal API intended for the Edge Runtime dashboard to retrieve gateway tokens without direct database access from edge functions.

### Query parameters

Expand Down