Eskyee · mintlify · Apr 8, 2026
diff --git 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
 
 <Note>To update agent configuration through the web proxy with session authentication, use [`PUT /api/agents/:id/config`](#update-agent-configuration) instead.</Note>
 
+## 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 |
 
-<Note>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.</Note>
+<Note>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.</Note>
 
 ## 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` |
 
 <Note>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.</Note>
 
@@ -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
@@ -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
 
 <Warning>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`.</Warning>
 
+<Note>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`.</Note>
+
 ### Errors
 
 | Code | Description |

diff --git 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 |
 
+<Note>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"`.</Note>
+
 **Root soul fields (`root.soul`):**
 
 | Field | Type | Description |

diff --git 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
 
-<Warning>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.</Warning>
-
 Swarms let you group multiple agents into a coordinated unit. Use swarms to orchestrate multi-agent workflows where agents collaborate on tasks.
 
+<Note>The Swarms API supports creating and listing swarms. Update and delete operations are not yet available.</Note>
+
 <Note>All swarm endpoints require session authentication and are scoped to the authenticated user's data through [row-level security](/security#row-level-security).</Note>
 
 ## 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
@@ -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"
         ]
       },
       {