From a4c7224a89b43bdb72bc58730dd7524738da0f2e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 8 Apr 2026 23:44:06 +0000 Subject: [PATCH] Update API docs for agents, billing, colony, and swarms endpoints Generated-By: mintlify-agent --- api-reference/agents.mdx | 103 ++++++++++++++++++++++++++++++++++++-- api-reference/billing.mdx | 11 ++++ api-reference/colony.mdx | 8 ++- api-reference/swarms.mdx | 6 +-- docs.json | 3 +- 5 files changed, 122 insertions(+), 9 deletions(-) diff --git a/api-reference/agents.mdx b/api-reference/agents.mdx index 1054542..e119e25 100644 --- a/api-reference/agents.mdx +++ b/api-reference/agents.mdx @@ -222,6 +222,77 @@ Updates an agent's metadata including plan, AI provider, and configuration. Requ To update agent configuration through the web proxy with session authentication, use [`PUT /api/agents/:id/config`](#update-agent-configuration) instead. +## Rename agent + +```http +PATCH /api/agents/:id +``` + +Renames an agent. Requires session authentication and ownership. The new name is also forwarded to the backend on a best-effort basis. + +### Request body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | New agent name. Must be between 1 and 64 characters. Leading and trailing whitespace is trimmed. | + +### Response + +```json +{ + "success": true, + "agent": { + "id": "agent_123", + "name": "Renamed Agent", + "status": "running", + "updatedAt": "2026-04-08T12:00:00.000Z" + } +} +``` + +### Errors + +| Code | Description | +|------|-------------| +| 400 | Name is required, or name exceeds 64 characters | +| 401 | Unauthorized | +| 404 | Agent not found | +| 500 | Failed to rename agent | + +## Sync agent to gateway + +```http +POST /api/agents/:id/sync +``` + +Triggers a manual resync of agent skills, memories, and files to the gateway. Use this when a previous provisioning sync failed or when you have updated agent data that needs to be pushed to the gateway. Requires session authentication. + +### Response + +```json +{ + "success": true, + "agentId": "agent_123", + "gatewayId": "gw_456", + "deployedAt": "2026-04-08T12:00:00.000Z", + "details": {} +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `agentId` | string | The agent that was synced | +| `gatewayId` | string | The gateway the agent was synced to | +| `deployedAt` | string | ISO 8601 timestamp of the sync | +| `details` | object | Additional deployment details from the sync operation | + +### Errors + +| Code | Description | +|------|-------------| +| 401 | Unauthorized | +| 500 | Sync failed. Response includes `details` and `agentId` fields. | + ## Delete agent ```http @@ -230,7 +301,7 @@ DELETE /api/agents/:id Stops and removes the agent's local Docker container, deallocates its port, and removes its metadata file. Requires bearer token authentication (backend). -### Response +### Response (backend) ```json { @@ -239,6 +310,17 @@ Stops and removes the agent's local Docker container, deallocates its port, and } ``` +### Response (web proxy) + +The web proxy deletes the agent record from the database, attempts to destroy the associated Railway service, and clears the user's runtime instance fields. + +```json +{ + "success": true, + "deleted": "agent_123" +} +``` + ### Errors | Code | Description | @@ -248,7 +330,7 @@ Stops and removes the agent's local Docker container, deallocates its port, and | 404 | Agent not found | | 500 | Failed to delete agent | -The backend uses best-effort cleanup (service destruction and metadata removal). If the agent metadata does not exist, the endpoint returns `404` before attempting cleanup. Container stop and removal failures are silently ignored. +The backend uses best-effort cleanup (service destruction and metadata removal). If the agent metadata does not exist, the endpoint returns `404` before attempting cleanup. Container stop and removal failures are silently ignored. The web proxy performs dual ownership verification — it checks both the agent's `userId` and the user's runtime instance ID before allowing deletion. ## Provision agent @@ -271,7 +353,19 @@ Provisions a new agent. Requires an active subscription unless the caller is an | `name` | string | Yes | Agent name | | `model` | string | No | AI model (default: `claude-opus-4-6`). Options: `claude-opus-4-6`, `gpt-4`, `custom` | | `config` | object | No | Agent configuration | -| `tier` | string | No | Subscription tier hint. Options: `starter`, `pro`, `enterprise`. This value is forwarded to the backend as the `plan` field (mapped to `solo`, `collective`, `label`, `network`). When omitted, the backend deployment defaults to `label`. | +| `tier` | string | No | Subscription tier hint. This value is normalized before being forwarded to the backend as the `plan` field. When omitted, the backend deployment defaults to `label`. See tier normalization below. | + +### Tier normalization + +The `tier` value is normalized before use. The following mappings are applied: + +| Input values | Normalized to | +|-------------|---------------| +| `starter`, `free`, `underground`, `solo` | `solo` | +| `pro`, `collective` | `collective` | +| `label` | `label` | +| `enterprise`, `network` | `network` | +| Any other value | `solo` | The web proxy enforces agent limits based on the subscription tier (`starter`: 1, `pro`: 3, `enterprise`: 100). The backend provisioning route (`POST /api/provision`) enforces its own limits (`solo`: 1, `collective`: 3, `label`: 10, `network`: 999999). The plan middleware enforces a separate set of agent limits for AI model access (`solo`: 1, `collective`: 10, `label`: 3, `network`: 100). The provisioning limits and middleware limits apply independently. The limit cannot be overridden in the request body. @@ -315,8 +409,9 @@ Admin status is determined by checking the session email against `ADMIN_EMAILS`. | 400 | Agent name is required | | 401 | Unauthorized | | 402 | Active subscription required to provision agents | -| 429 | Agent limit reached for your plan (web proxy). Response includes `current` (agent count) and `limit` fields. Limits: `starter` 1, `pro` 3, `enterprise` 100. Users without a recognized plan default to a limit of 1. The backend returns `402` with code `AGENT_LIMIT_REACHED` for the same condition. | +| 429 | Agent limit reached for your plan. Response includes `current` (agent count) and `limit` fields. Tier limits after normalization: `solo` 1, `collective` 3, `label` 10, `network` 100. Admin users bypass this limit. | | 500 | Failed to provision agent | +| 503 | Managed runtime provisioning is not configured. Returned when the managed runtime URL is not set in the environment. | ## Token sponsorship simulator diff --git a/api-reference/billing.mdx b/api-reference/billing.mdx index 62b771a..42e79cc 100644 --- a/api-reference/billing.mdx +++ b/api-reference/billing.mdx @@ -49,6 +49,11 @@ Returns the available plans, the authenticated user's current plan, subscription }, "currentPlan": "solo", "subscriptionStatus": "active", + "trial": { + "expired": false, + "daysLeft": 7, + "endsAt": "2026-04-15T00:00:00.000Z" + }, "byokEnabled": false, "usage": { "dailyUnits": 600, @@ -65,6 +70,10 @@ Returns the available plans, the authenticated user's current plan, subscription | `plans` | object | Map of available plans with pricing and features | | `currentPlan` | string | User's current plan. One of `solo`, `collective`, `label`, or `network`. Users who subscribed via the Stripe checkout flow have plans like `solo`, `collective`, `label`, or `network`. | | `subscriptionStatus` | string | Stripe subscription status (`active`, `inactive`, etc.) | +| `trial` | object \| null | Trial status. Present when the user has an active or expired trial. `null` when no trial data exists. | +| `trial.expired` | boolean | Whether the trial period has ended | +| `trial.daysLeft` | number | Number of days remaining in the trial | +| `trial.endsAt` | string | ISO 8601 timestamp when the trial ends | | `byokEnabled` | boolean | Whether BYOK mode is active | | `usage.dailyUnits` | number | Daily unit allowance for the current plan | | `usage.used` | number | Units used today | @@ -74,6 +83,8 @@ Returns the available plans, the authenticated user's current plan, subscription The billing endpoint internally defines a legacy plan catalog (`starter` at $19/mo, `pro` at $39/mo, `scale` at $79/mo) which may appear in responses for users who subscribed before the current plan names were introduced. The primary checkout flow and provisioning endpoints use the current plan names (`solo`, `collective`, `label`, `network`). If you encounter legacy plan names in billing responses, they map to the current plans as follows: `starter` → `solo`, `pro` → `collective`, `scale` → `label`. +The `trial` object is only present when the user has trial data. When the user has never had a trial or the trial record has been removed, `trial` is `null`. + ### Errors | Code | Description | diff --git a/api-reference/colony.mdx b/api-reference/colony.mdx index e118376..8f5e3e2 100644 --- a/api-reference/colony.mdx +++ b/api-reference/colony.mdx @@ -84,6 +84,8 @@ curl -X GET "https://agentbot.sh/api/colony/status?action=tree" \ "root": { "address": "0x1234...5678", "designation": "Atlas Prime", + "dashboardUrl": "/dashboard/borg", + "serviceUrl": "https://soul.example.com", "fitness": { "total": 0.85, "prediction": 0.78, @@ -182,13 +184,17 @@ curl -X GET "https://agentbot.sh/api/colony/status?action=tree" \ |-------|------|-------------| | `address` | string | Root node wallet address. Falls back to the zero address when identity data is unavailable. | | `designation` | string \| null | Root node display name | +| `dashboardUrl` | string | Internal dashboard path for the soul UI (for example, `/dashboard/borg`) | +| `serviceUrl` | string | Soul service URL that served the request. Reflects the fallback host when `degraded` is `true`. | | `fitness` | object \| null | Multi-dimensional fitness scores with `total`, `prediction`, and `execution` | -| `wallet_balance` | object \| null | Wallet balance with `formatted` amount and `token` symbol. Returns `{ "formatted": "0.00", "token": "USDC.e" }` when identity data is unavailable. | +| `wallet_balance` | object \| null | On-chain wallet balance with `formatted` amount and `token` symbol. The balance is read from the Tempo network and checks USDC.e, pathUSD, and USDT0 token contracts. Returns `{ "formatted": "0.00", "token": "USDC.e" }` when identity data is unavailable. Returns `null` when the balance lookup fails entirely. | | `clone_available` | boolean | Whether this node can create clones | | `clone_price` | string | Price to clone this node | | `soul` | object | Soul cognitive state | | `colony` | object \| null | Colony coordination data, or `null` if unavailable | +The `wallet_balance` field reads on-chain token balances from the Tempo network (chain ID 4217, RPC `https://rpc.tempo.xyz`). It checks the following ERC-20 tokens in order and returns the first non-zero balance: USDC.e, pathUSD, USDT0. If all balances are zero or the RPC call fails, the `formatted` value is `"0.00"` with `token` set to `"USDC.e"`. + **Root soul fields (`root.soul`):** | Field | Type | Description | diff --git a/api-reference/swarms.mdx b/api-reference/swarms.mdx index 8d55ff6..451abd9 100644 --- a/api-reference/swarms.mdx +++ b/api-reference/swarms.mdx @@ -5,10 +5,10 @@ description: "Create and manage agent swarms for coordinated multi-agent workflo # Swarms API -The Swarms API is not live on Agentbot. This page is kept as an internal roadmap/spec reference and is intentionally not linked from the main docs navigation. - Swarms let you group multiple agents into a coordinated unit. Use swarms to orchestrate multi-agent workflows where agents collaborate on tasks. +The Swarms API supports creating and listing swarms. Update and delete operations are not yet available. + All swarm endpoints require session authentication and are scoped to the authenticated user's data through [row-level security](/security#row-level-security). ## List swarms @@ -79,7 +79,7 @@ Creates a new agent swarm. The swarm is enabled by default. | `name` | string | Yes | Swarm name. Must be between 1 and 100 characters | | `description` | string | No | Optional description | | `agents` | string[] | No | Array of agent IDs to include in the swarm. Defaults to an empty array | -| `config` | object | No | Optional configuration object | +| `config` | object | No | Reserved for future use. Accepted but not stored. | ### Response diff --git a/docs.json b/docs.json index f5c6a70..9ed9e58 100644 --- a/docs.json +++ b/docs.json @@ -157,7 +157,8 @@ "api-reference/guestlist", "api-reference/partner", "api-reference/generate-video", - "api-reference/generate-music" + "api-reference/generate-music", + "api-reference/swarms" ] }, {