From bfd75b140851b32588199d83ece437ad639e3d07 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 8 Apr 2026 03:27:43 +0000 Subject: [PATCH] Align API docs with current endpoint behavior Generated-By: mintlify-agent --- api-reference/agents.mdx | 8 ++--- api-reference/ai.mdx | 56 +++++++++++++++++++++++++++++++++ api-reference/orchestration.mdx | 7 ++--- api-reference/referrals.mdx | 43 +++++++++++++++++++++++++ api-reference/registration.mdx | 4 ++- 5 files changed, 109 insertions(+), 9 deletions(-) diff --git a/api-reference/agents.mdx b/api-reference/agents.mdx index 814c7b0..1122056 100644 --- a/api-reference/agents.mdx +++ b/api-reference/agents.mdx @@ -7,7 +7,7 @@ description: "Create, manage, and interact with agents" Create, manage, and interact with agents. -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. +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. ## List agents @@ -15,11 +15,11 @@ Create, manage, and interact with agents. 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 [ @@ -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`) | -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. +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. ## Create agent diff --git a/api-reference/ai.mdx b/api-reference/ai.mdx index 348a264..767d7f0 100644 --- a/api-reference/ai.mdx +++ b/api-reference/ai.mdx @@ -11,6 +11,62 @@ Endpoints for interacting with AI models through a unified provider layer. These All `/api/ai/*` endpoints share a rate limit of 30 requests per minute per IP, not just the chat endpoint. +## 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. | + +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`. + +### Errors + +| Code | Description | +|------|-------------| +| 500 | Failed to fetch models — upstream OpenRouter API error or invalid response | + ## Health check ```http diff --git a/api-reference/orchestration.mdx b/api-reference/orchestration.mdx index 54f0770..b84aa3b 100644 --- a/api-reference/orchestration.mdx +++ b/api-reference/orchestration.mdx @@ -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. | @@ -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 | -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. +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. ### Serial failure behavior diff --git a/api-reference/referrals.mdx b/api-reference/referrals.mdx index 142b5d8..9b58535 100644 --- a/api-reference/referrals.mdx +++ b/api-reference/referrals.mdx @@ -52,3 +52,46 @@ Requires session authentication. Returns the authenticated user's referral code, | 500 | Failed to fetch referrals | 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. + +## 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 | diff --git a/api-reference/registration.mdx b/api-reference/registration.mdx index 9fe3133..a959c99 100644 --- a/api-reference/registration.mdx +++ b/api-reference/registration.mdx @@ -191,11 +191,13 @@ Returns registered installations belonging to the authenticated user. Results ar ## Get registration token (internal) +**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. + ```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