@octavus/docs 1.0.0 → 2.1.0

package/dist/{chunk-WJ2W3DUC.js → chunk-HFF2TVGV.js}

@@ -59,7 +59,7 @@ var docs_default = [
     section: "server-sdk",
     title: "CLI",
     description: "Command-line interface for validating and syncing agent definitions.",
-    content: '\n# Octavus CLI\n\nThe `@octavus/cli` package provides a command-line interface for validating and syncing agent definitions from your local filesystem to the Octavus platform.\n\n**Current version:** `1.0.0`\n\n## Installation\n\n```bash\nnpm install --save-dev @octavus/cli\n```\n\n## Configuration\n\nThe CLI requires an API key with agent management permissions.\n\n### Environment Variables\n\n| Variable              | Description                                             |\n| --------------------- | ------------------------------------------------------- |\n| `OCTAVUS_CLI_API_KEY` | API key with agent management permissions (recommended) |\n| `OCTAVUS_API_KEY`     | Fallback if `OCTAVUS_CLI_API_KEY` not set               |\n| `OCTAVUS_API_URL`     | Optional, defaults to `https://octavus.ai`              |\n\n### Two-Key Strategy (Recommended)\n\nFor production deployments, use separate API keys:\n\n```bash\n# CI/CD or .env.local (not committed)\nOCTAVUS_CLI_API_KEY=oct_sk_...  # Agent management permissions\n\n# Production .env\nOCTAVUS_API_KEY=oct_sk_...      # Session-only permissions\n```\n\nThis ensures production servers only have session permissions (smaller blast radius if leaked), while agent management is restricted to development/CI environments.\n\n### Multiple Environments\n\nUse separate Octavus projects for staging and production, each with their own API keys. The `--env` flag lets you load different environment files:\n\n```bash\n# Local development (default: .env)\noctavus sync ./agents/my-agent\n\n# Staging project\noctavus --env .env.staging sync ./agents/my-agent\n\n# Production project\noctavus --env .env.production sync ./agents/my-agent\n```\n\nExample environment files:\n\n```bash\n# .env.staging (syncs to your staging project)\nOCTAVUS_CLI_API_KEY=oct_sk_staging_project_key...\n\n# .env.production (syncs to your production project)\nOCTAVUS_CLI_API_KEY=oct_sk_production_project_key...\n```\n\nEach project has its own agents, so you\'ll get different agent IDs per environment.\n\n## Global Options\n\n| Option         | Description                                             |\n| -------------- | ------------------------------------------------------- |\n| `--env <file>` | Load environment from a specific file (default: `.env`) |\n| `--help`       | Show help                                               |\n| `--version`    | Show version                                            |\n\n## Commands\n\n### `octavus sync <path>`\n\nSync an agent definition to the platform. Creates the agent if it doesn\'t exist, or updates it if it does.\n\n```bash\noctavus sync ./agents/my-agent\n```\n\n**Options:**\n\n- `--json` \u2014 Output as JSON (for CI/CD parsing)\n- `--quiet` \u2014 Suppress non-essential output\n\n**Example output:**\n\n```\n\u2139 Reading agent from ./agents/my-agent...\n\u2139 Syncing support-chat...\n\u2713 Created: support-chat\n  Agent ID: clxyz123abc456\n```\n\n### `octavus validate <path>`\n\nValidate an agent definition without saving. Useful for CI/CD pipelines.\n\n```bash\noctavus validate ./agents/my-agent\n```\n\n**Exit codes:**\n\n- `0` \u2014 Validation passed\n- `1` \u2014 Validation errors\n- `2` \u2014 Configuration errors (missing API key, etc.)\n\n### `octavus list`\n\nList all agents in your project.\n\n```bash\noctavus list\n```\n\n**Example output:**\n\n```\nSLUG                  NAME                            FORMAT        ID\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nsupport-chat          Support Chat Agent              interactive   clxyz123abc456\n\n1 agent(s)\n```\n\n### `octavus get <slug>`\n\nGet details about a specific agent by its slug.\n\n```bash\noctavus get support-chat\n```\n\n## Agent Directory Structure\n\nThe CLI expects agent definitions in a specific directory structure:\n\n```\nmy-agent/\n\u251C\u2500\u2500 settings.json     # Required: Agent metadata\n\u251C\u2500\u2500 protocol.yaml     # Required: Agent protocol\n\u2514\u2500\u2500 prompts/          # Optional: Prompt templates\n    \u251C\u2500\u2500 system.md\n    \u2514\u2500\u2500 user-message.md\n```\n\n### settings.json\n\n```json\n{\n  "slug": "my-agent",\n  "name": "My Agent",\n  "description": "A helpful assistant",\n  "format": "interactive"\n}\n```\n\n### protocol.yaml\n\nSee the [Protocol documentation](/docs/protocol/overview) for details on protocol syntax.\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Validate and Sync Agents\n\non:\n  push:\n    branches: [main]\n    paths:\n      - \'agents/**\'\n\njobs:\n  sync:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \'22\'\n\n      - run: npm install\n\n      - name: Validate agent\n        run: npx octavus validate ./agents/support-chat\n        env:\n          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}\n\n      - name: Sync agent\n        run: npx octavus sync ./agents/support-chat\n        env:\n          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}\n```\n\n### Package.json Scripts\n\nAdd sync scripts to your `package.json`:\n\n```json\n{\n  "scripts": {\n    "agents:validate": "octavus validate ./agents/my-agent",\n    "agents:sync": "octavus sync ./agents/my-agent"\n  },\n  "devDependencies": {\n    "@octavus/cli": "^0.1.0"\n  }\n}\n```\n\n## Workflow\n\nThe recommended workflow for managing agents:\n\n1. **Define agent locally** \u2014 Create `settings.json`, `protocol.yaml`, and prompts\n2. **Validate** \u2014 Run `octavus validate ./my-agent` to check for errors\n3. **Sync** \u2014 Run `octavus sync ./my-agent` to push to platform\n4. **Store agent ID** \u2014 Save the output ID in an environment variable\n5. **Use in app** \u2014 Read the ID from env and pass to `client.agentSessions.create()`\n\n```bash\n# After syncing: octavus sync ./agents/support-chat\n# Output: Agent ID: clxyz123abc456\n\n# Add to your .env file\nOCTAVUS_SUPPORT_AGENT_ID=clxyz123abc456\n```\n\n```typescript\nconst agentId = process.env.OCTAVUS_SUPPORT_AGENT_ID;\n\nconst sessionId = await client.agentSessions.create(agentId, {\n  COMPANY_NAME: \'Acme Corp\',\n});\n```\n',
+    content: '\n# Octavus CLI\n\nThe `@octavus/cli` package provides a command-line interface for validating and syncing agent definitions from your local filesystem to the Octavus platform.\n\n**Current version:** `1.0.0`\n\n## Installation\n\n```bash\nnpm install --save-dev @octavus/cli\n```\n\n## Configuration\n\nThe CLI requires an API key with the **Agents** permission.\n\n### Environment Variables\n\n| Variable              | Description                                    |\n| --------------------- | ---------------------------------------------- |\n| `OCTAVUS_CLI_API_KEY` | API key with "Agents" permission (recommended) |\n| `OCTAVUS_API_KEY`     | Fallback if `OCTAVUS_CLI_API_KEY` not set      |\n| `OCTAVUS_API_URL`     | Optional, defaults to `https://octavus.ai`     |\n\n### Two-Key Strategy (Recommended)\n\nFor production deployments, use separate API keys with minimal permissions:\n\n```bash\n# CI/CD or .env.local (not committed)\nOCTAVUS_CLI_API_KEY=oct_sk_...  # "Agents" permission only\n\n# Production .env\nOCTAVUS_API_KEY=oct_sk_...      # "Sessions" permission only\n```\n\nThis ensures production servers only have session permissions (smaller blast radius if leaked), while agent management is restricted to development/CI environments.\n\n### Multiple Environments\n\nUse separate Octavus projects for staging and production, each with their own API keys. The `--env` flag lets you load different environment files:\n\n```bash\n# Local development (default: .env)\noctavus sync ./agents/my-agent\n\n# Staging project\noctavus --env .env.staging sync ./agents/my-agent\n\n# Production project\noctavus --env .env.production sync ./agents/my-agent\n```\n\nExample environment files:\n\n```bash\n# .env.staging (syncs to your staging project)\nOCTAVUS_CLI_API_KEY=oct_sk_staging_project_key...\n\n# .env.production (syncs to your production project)\nOCTAVUS_CLI_API_KEY=oct_sk_production_project_key...\n```\n\nEach project has its own agents, so you\'ll get different agent IDs per environment.\n\n## Global Options\n\n| Option         | Description                                             |\n| -------------- | ------------------------------------------------------- |\n| `--env <file>` | Load environment from a specific file (default: `.env`) |\n| `--help`       | Show help                                               |\n| `--version`    | Show version                                            |\n\n## Commands\n\n### `octavus sync <path>`\n\nSync an agent definition to the platform. Creates the agent if it doesn\'t exist, or updates it if it does.\n\n```bash\noctavus sync ./agents/my-agent\n```\n\n**Options:**\n\n- `--json` \u2014 Output as JSON (for CI/CD parsing)\n- `--quiet` \u2014 Suppress non-essential output\n\n**Example output:**\n\n```\n\u2139 Reading agent from ./agents/my-agent...\n\u2139 Syncing support-chat...\n\u2713 Created: support-chat\n  Agent ID: clxyz123abc456\n```\n\n### `octavus validate <path>`\n\nValidate an agent definition without saving. Useful for CI/CD pipelines.\n\n```bash\noctavus validate ./agents/my-agent\n```\n\n**Exit codes:**\n\n- `0` \u2014 Validation passed\n- `1` \u2014 Validation errors\n- `2` \u2014 Configuration errors (missing API key, etc.)\n\n### `octavus list`\n\nList all agents in your project.\n\n```bash\noctavus list\n```\n\n**Example output:**\n\n```\nSLUG                  NAME                            FORMAT        ID\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nsupport-chat          Support Chat Agent              interactive   clxyz123abc456\n\n1 agent(s)\n```\n\n### `octavus get <slug>`\n\nGet details about a specific agent by its slug.\n\n```bash\noctavus get support-chat\n```\n\n## Agent Directory Structure\n\nThe CLI expects agent definitions in a specific directory structure:\n\n```\nmy-agent/\n\u251C\u2500\u2500 settings.json     # Required: Agent metadata\n\u251C\u2500\u2500 protocol.yaml     # Required: Agent protocol\n\u2514\u2500\u2500 prompts/          # Optional: Prompt templates\n    \u251C\u2500\u2500 system.md\n    \u2514\u2500\u2500 user-message.md\n```\n\n### settings.json\n\n```json\n{\n  "slug": "my-agent",\n  "name": "My Agent",\n  "description": "A helpful assistant",\n  "format": "interactive"\n}\n```\n\n### protocol.yaml\n\nSee the [Protocol documentation](/docs/protocol/overview) for details on protocol syntax.\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Validate and Sync Agents\n\non:\n  push:\n    branches: [main]\n    paths:\n      - \'agents/**\'\n\njobs:\n  sync:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \'22\'\n\n      - run: npm install\n\n      - name: Validate agent\n        run: npx octavus validate ./agents/support-chat\n        env:\n          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}\n\n      - name: Sync agent\n        run: npx octavus sync ./agents/support-chat\n        env:\n          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}\n```\n\n### Package.json Scripts\n\nAdd sync scripts to your `package.json`:\n\n```json\n{\n  "scripts": {\n    "agents:validate": "octavus validate ./agents/my-agent",\n    "agents:sync": "octavus sync ./agents/my-agent"\n  },\n  "devDependencies": {\n    "@octavus/cli": "^0.1.0"\n  }\n}\n```\n\n## Workflow\n\nThe recommended workflow for managing agents:\n\n1. **Define agent locally** \u2014 Create `settings.json`, `protocol.yaml`, and prompts\n2. **Validate** \u2014 Run `octavus validate ./my-agent` to check for errors\n3. **Sync** \u2014 Run `octavus sync ./my-agent` to push to platform\n4. **Store agent ID** \u2014 Save the output ID in an environment variable\n5. **Use in app** \u2014 Read the ID from env and pass to `client.agentSessions.create()`\n\n```bash\n# After syncing: octavus sync ./agents/support-chat\n# Output: Agent ID: clxyz123abc456\n\n# Add to your .env file\nOCTAVUS_SUPPORT_AGENT_ID=clxyz123abc456\n```\n\n```typescript\nconst agentId = process.env.OCTAVUS_SUPPORT_AGENT_ID;\n\nconst sessionId = await client.agentSessions.create(agentId, {\n  COMPANY_NAME: \'Acme Corp\',\n});\n```\n',
     excerpt: "Octavus CLI The  package provides a command-line interface for validating and syncing agent definitions from your local filesystem to the Octavus platform. Current version:   Installation ...",
     order: 5
   },
@@ -239,7 +239,7 @@ var docs_default = [
     section: "api-reference",
     title: "Overview",
     description: "REST API overview and authentication.",
-    content: '\n# API Reference\n\nThe Octavus API is a RESTful API that enables programmatic access to agent management and session execution.\n\n## Base URL\n\n```\nhttps://octavus.ai\n```\n\n## Authentication\n\nAll API requests require authentication using a Bearer token:\n\n```bash\ncurl -H "Authorization: Bearer YOUR_API_KEY" \\\n  https://octavus.ai/api/agents\n```\n\nAPI keys can be created in the Octavus Platform under your project\'s **API Keys** page.\n\n## Response Format\n\nAll responses are JSON. Success responses return the data directly (not wrapped in a `data` field).\n\n### Success Response\n\n```json\n{\n  "sessionId": "sess_abc123"\n}\n```\n\n### Error Response\n\n```json\n{\n  "error": {\n    "code": "NOT_FOUND",\n    "message": "Agent not found"\n  }\n}\n```\n\n## HTTP Status Codes\n\n| Code | Description                               |\n| ---- | ----------------------------------------- |\n| 200  | Success                                   |\n| 201  | Created                                   |\n| 400  | Bad Request - Invalid parameters          |\n| 401  | Unauthorized - Missing or invalid API key |\n| 403  | Forbidden - Insufficient permissions      |\n| 404  | Not Found                                 |\n| 500  | Internal Server Error                     |\n\n## Endpoints Overview\n\n### Agents\n\n| Method | Endpoint          | Description     |\n| ------ | ----------------- | --------------- |\n| GET    | `/api/agents`     | List all agents |\n| GET    | `/api/agents/:id` | Get agent by ID |\n| POST   | `/api/agents`     | Create agent    |\n| PATCH  | `/api/agents/:id` | Update agent    |\n\n### Sessions\n\n| Method | Endpoint                          | Description           |\n| ------ | --------------------------------- | --------------------- |\n| POST   | `/api/agent-sessions`             | Create session        |\n| GET    | `/api/agent-sessions/:id`         | Get session state     |\n| POST   | `/api/agent-sessions/:id/trigger` | Execute trigger (SSE) |\n\n## Streaming\n\nThe trigger endpoint returns Server-Sent Events (SSE):\n\n```bash\ncurl -N -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{"triggerName": "user-message", "input": {"USER_MESSAGE": "Hello"}}\' \\\n  https://octavus.ai/api/agent-sessions/SESSION_ID/trigger\n```\n\nResponse format:\n\n```\ndata: {"type":"start","messageId":"..."}\n\ndata: {"type":"block-start","blockId":"...","blockName":"Respond","blockType":"next-message","display":"stream"}\n\ndata: {"type":"text-start","id":"..."}\n\ndata: {"type":"text-delta","id":"...","delta":"Hello"}\n\ndata: {"type":"text-delta","id":"...","delta":"!"}\n\ndata: {"type":"text-end","id":"..."}\n\ndata: {"type":"block-end","blockId":"..."}\n\ndata: {"type":"finish","finishReason":"stop"}\n\ndata: [DONE]\n```\n\n## SDKs\n\nWe recommend using our SDKs instead of calling the API directly:\n\n- **Server SDK**: `@octavus/server-sdk` - For Node.js backends\n- **React SDK**: `@octavus/react` - For React applications\n- **Client SDK**: `@octavus/client-sdk` - For other frontend frameworks\n\nThe SDKs handle authentication, streaming, and tool execution automatically.\n',
+    content: '\n# API Reference\n\nThe Octavus API is a RESTful API that enables programmatic access to agent management and session execution.\n\n## Base URL\n\n```\nhttps://octavus.ai\n```\n\n## Authentication\n\nAll API requests require authentication using a Bearer token:\n\n```bash\ncurl -H "Authorization: Bearer YOUR_API_KEY" \\\n  https://octavus.ai/api/agents\n```\n\nAPI keys can be created in the Octavus Platform under your project\'s **API Keys** page.\n\n## API Key Permissions\n\nAPI keys have two permission scopes:\n\n| Permission   | Description                                              | Used By    |\n| ------------ | -------------------------------------------------------- | ---------- |\n| **Sessions** | Create and manage sessions, trigger agents, upload files | Server SDK |\n| **Agents**   | Create, update, and validate agent definitions           | CLI        |\n\nBoth permissions allow reading agent definitions (needed by CLI for sync and Server SDK for sessions).\n\n**Recommended setup:** Use separate API keys for different purposes:\n\n- **CLI key** with only "Agents" permission for CI/CD and development\n- **Server key** with only "Sessions" permission for production applications\n\nThis limits the blast radius if a key is compromised.\n\n## Response Format\n\nAll responses are JSON. Success responses return the data directly (not wrapped in a `data` field).\n\n### Success Response\n\n```json\n{\n  "sessionId": "sess_abc123"\n}\n```\n\n### Error Response\n\n```json\n{\n  "error": {\n    "code": "NOT_FOUND",\n    "message": "Agent not found"\n  }\n}\n```\n\n## HTTP Status Codes\n\n| Code | Description                               |\n| ---- | ----------------------------------------- |\n| 200  | Success                                   |\n| 201  | Created                                   |\n| 400  | Bad Request - Invalid parameters          |\n| 401  | Unauthorized - Missing or invalid API key |\n| 403  | Forbidden - Insufficient permissions      |\n| 404  | Not Found                                 |\n| 500  | Internal Server Error                     |\n\n## Endpoints Overview\n\n### Agents\n\n| Method | Endpoint          | Description     |\n| ------ | ----------------- | --------------- |\n| GET    | `/api/agents`     | List all agents |\n| GET    | `/api/agents/:id` | Get agent by ID |\n| POST   | `/api/agents`     | Create agent    |\n| PATCH  | `/api/agents/:id` | Update agent    |\n\n### Sessions\n\n| Method | Endpoint                          | Description           |\n| ------ | --------------------------------- | --------------------- |\n| POST   | `/api/agent-sessions`             | Create session        |\n| GET    | `/api/agent-sessions/:id`         | Get session state     |\n| POST   | `/api/agent-sessions/:id/trigger` | Execute trigger (SSE) |\n\n## Streaming\n\nThe trigger endpoint returns Server-Sent Events (SSE):\n\n```bash\ncurl -N -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{"triggerName": "user-message", "input": {"USER_MESSAGE": "Hello"}}\' \\\n  https://octavus.ai/api/agent-sessions/SESSION_ID/trigger\n```\n\nResponse format:\n\n```\ndata: {"type":"start","messageId":"..."}\n\ndata: {"type":"block-start","blockId":"...","blockName":"Respond","blockType":"next-message","display":"stream"}\n\ndata: {"type":"text-start","id":"..."}\n\ndata: {"type":"text-delta","id":"...","delta":"Hello"}\n\ndata: {"type":"text-delta","id":"...","delta":"!"}\n\ndata: {"type":"text-end","id":"..."}\n\ndata: {"type":"block-end","blockId":"..."}\n\ndata: {"type":"finish","finishReason":"stop"}\n\ndata: [DONE]\n```\n\n## SDKs\n\nWe recommend using our SDKs instead of calling the API directly:\n\n- **Server SDK**: `@octavus/server-sdk` - For Node.js backends\n- **React SDK**: `@octavus/react` - For React applications\n- **Client SDK**: `@octavus/client-sdk` - For other frontend frameworks\n\nThe SDKs handle authentication, streaming, and tool execution automatically.\n',
     excerpt: "API Reference The Octavus API is a RESTful API that enables programmatic access to agent management and session execution.  Base URL  Authentication All API requests require authentication using a...",
     order: 1
   },
@@ -248,8 +248,8 @@ var docs_default = [
     section: "api-reference",
     title: "Sessions",
     description: "Session management API endpoints.",
-    content: '\n# Sessions API\n\nSessions represent conversations with agents. They store conversation history, resources, and variables.\n\n## Create Session\n\nCreate a new agent session.\n\n```\nPOST /api/agent-sessions\n```\n\n### Request Body\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "input": {\n    "COMPANY_NAME": "Acme Corp",\n    "PRODUCT_NAME": "Widget Pro",\n    "USER_ID": "user-123"\n  }\n}\n```\n\n| Field     | Type   | Required | Description                           |\n| --------- | ------ | -------- | ------------------------------------- |\n| `agentId` | string | Yes      | Agent ID (the `id` field, not `slug`) |\n| `input`   | object | No       | Input variables for the agent         |\n\n> **Getting the agent ID:** Copy the ID from the agent URL in the [platform](https://octavus.ai) (e.g., `octavus.ai/agents/clxyz123`), or use the [CLI](/docs/server-sdk/cli) (`octavus sync ./agents/my-agent`) for local development workflows.\n\n### Response\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agent-sessions \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "agentId": "cm5xvz7k80001abcd",\n    "input": {\n      "COMPANY_NAME": "Acme Corp",\n      "PRODUCT_NAME": "Widget Pro"\n    }\n  }\'\n```\n\n## Get Session\n\nRetrieve session state. Returns UI-ready messages for active sessions, or expiration info for expired sessions.\n\n```\nGET /api/agent-sessions/:sessionId\n```\n\n### Query Parameters\n\n| Parameter | Type   | Description                                          |\n| --------- | ------ | ---------------------------------------------------- |\n| `format`  | string | Optional. Use `format=ui` for UI-ready messages only |\n\n### Response (Active Session)\n\nWhen the session is active, the response includes `UIMessage` objects:\n\n```json\n{\n  "id": "cm5xyz123abc456def",\n  "agentId": "cm5xvz7k80001abcd",\n  "status": "active",\n  "input": {\n    "COMPANY_NAME": "Acme Corp",\n    "PRODUCT_NAME": "Widget Pro"\n  },\n  "variables": {},\n  "resources": {\n    "CONVERSATION_SUMMARY": ""\n  },\n  "messages": [\n    {\n      "id": "1702345800000-xyz789a",\n      "role": "user",\n      "parts": [{ "type": "text", "text": "How do I reset my password?", "status": "done" }],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:00.000Z"\n    },\n    {\n      "id": "1702345805000-def456b",\n      "role": "assistant",\n      "parts": [\n        { "type": "text", "text": "I can help you reset your password...", "status": "done" }\n      ],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:05.000Z"\n    }\n  ],\n  "createdAt": "2024-01-15T10:30:00Z",\n  "updatedAt": "2024-01-15T10:30:05Z"\n}\n```\n\n### Response (Expired Session)\n\nWhen the session has expired, the response indicates the expiration status:\n\n```json\n{\n  "status": "expired",\n  "sessionId": "cm5xyz123abc456def",\n  "agentId": "cm5xvz7k80001abcd",\n  "createdAt": "2024-01-15T10:30:00Z"\n}\n```\n\nUse the [Restore Session](#restore-session) endpoint to restore an expired session from stored messages.\n\n````\n\n### UIMessage Parts\n\nMessages contain typed `parts` that preserve content ordering:\n\n| Part Type | Description |\n|-----------|-------------|\n| `text` | Text content with `text` and `status` fields |\n| `reasoning` | Extended reasoning with `text` and `status` fields |\n| `tool-call` | Tool execution with `toolCallId`, `toolName`, `displayName`, `args`, `result`, `status` |\n| `operation` | Internal operations with `operationId`, `name`, `operationType`, `status` |\n| `file` | File attachment with `id`, `mediaType`, `url`, `filename`, `size` |\n| `source` | Source reference with `sourceType`, `id`, `url`, `title` |\n| `object` | Structured output with `id`, `typeName`, `object`, `status` |\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agent-sessions/:sessionId \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n````\n\n## Restore Session\n\nRestore an expired session from stored messages. This allows you to continue a conversation after the server-side state has expired.\n\n```\nPOST /api/agent-sessions/:sessionId/restore\n```\n\n### Request Body\n\n```json\n{\n  "messages": [\n    {\n      "id": "1702345800000-xyz789a",\n      "role": "user",\n      "parts": [{ "type": "text", "text": "How do I reset my password?", "status": "done" }],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:00.000Z"\n    }\n  ],\n  "input": {\n    "COMPANY_NAME": "Acme Corp"\n  }\n}\n```\n\n| Field      | Type        | Required | Description                                                    |\n| ---------- | ----------- | -------- | -------------------------------------------------------------- |\n| `messages` | UIMessage[] | Yes      | Previously stored chat history                                 |\n| `input`    | object      | No       | Session input for system prompt interpolation (same as create) |\n\n### Response\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def",\n  "restored": true\n}\n```\n\n| Field       | Type    | Description                                                             |\n| ----------- | ------- | ----------------------------------------------------------------------- |\n| `sessionId` | string  | The session ID                                                          |\n| `restored`  | boolean | `true` if restored from messages, `false` if session was already active |\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agent-sessions/:sessionId/restore \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "messages": [...],\n    "input": { "COMPANY_NAME": "Acme Corp" }\n  }\'\n```\n\n> **Note**: Store the `UIMessage[]` array after each interaction to enable restoration. The restore endpoint reconstructs the conversation state from these messages.\n\n## Trigger Session\n\nExecute a trigger on a session. Returns a Server-Sent Events stream.\n\n```\nPOST /api/agent-sessions/:sessionId/trigger\n```\n\n### Request Body\n\n```json\n{\n  "triggerName": "user-message",\n  "input": {\n    "USER_MESSAGE": "How do I reset my password?"\n  },\n  "toolResults": []\n}\n```\n\n| Field         | Type   | Required | Description                                    |\n| ------------- | ------ | -------- | ---------------------------------------------- |\n| `triggerName` | string | Yes      | Name of the trigger to execute                 |\n| `input`       | object | No       | Input variables for the trigger                |\n| `toolResults` | array  | No       | Tool results for continuation (handled by SDK) |\n\n### Response\n\nReturns `text/event-stream` with SSE events:\n\n```\ndata: {"type":"start","messageId":"msg-123"}\n\ndata: {"type":"block-start","blockId":"b1","blockName":"Add user message","blockType":"add-message","display":"hidden"}\n\ndata: {"type":"block-end","blockId":"b1"}\n\ndata: {"type":"block-start","blockId":"b2","blockName":"Respond to user","blockType":"next-message","display":"stream","outputToChat":true}\n\ndata: {"type":"text-start","id":"t1"}\n\ndata: {"type":"text-delta","id":"t1","delta":"I"}\n\ndata: {"type":"text-delta","id":"t1","delta":" can"}\n\ndata: {"type":"text-delta","id":"t1","delta":" help"}\n\ndata: {"type":"text-delta","id":"t1","delta":" you"}\n\ndata: {"type":"text-delta","id":"t1","delta":" reset"}\n\ndata: {"type":"text-delta","id":"t1","delta":" your"}\n\ndata: {"type":"text-delta","id":"t1","delta":" password"}\n\ndata: {"type":"text-delta","id":"t1","delta":"!"}\n\ndata: {"type":"text-end","id":"t1"}\n\ndata: {"type":"block-end","blockId":"b2"}\n\ndata: {"type":"finish","finishReason":"stop"}\n\ndata: [DONE]\n```\n\n### Event Types\n\n| Event                   | Description                        |\n| ----------------------- | ---------------------------------- |\n| `start`                 | Stream started                     |\n| `finish`                | Execution complete                 |\n| `error`                 | Error occurred                     |\n| `block-start`           | Execution block started            |\n| `block-end`             | Execution block completed          |\n| `text-start`            | Text generation started            |\n| `text-delta`            | Incremental text content           |\n| `text-end`              | Text generation ended              |\n| `reasoning-start`       | Extended reasoning started         |\n| `reasoning-delta`       | Reasoning content                  |\n| `reasoning-end`         | Extended reasoning ended           |\n| `tool-input-start`      | Tool call initiated                |\n| `tool-input-delta`      | Tool arguments streaming           |\n| `tool-input-end`        | Tool arguments streaming ended     |\n| `tool-input-available`  | Tool input complete                |\n| `tool-output-available` | Tool completed with result         |\n| `tool-output-error`     | Tool failed                        |\n| `tool-request`          | Platform requesting tool execution |\n| `file-available`        | File ready for display/download    |\n| `resource-update`       | Resource value changed             |\n\n### Example\n\n```bash\ncurl -N -X POST https://octavus.ai/api/agent-sessions/:sessionId/trigger \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "triggerName": "user-message",\n    "input": { "USER_MESSAGE": "How do I reset my password?" }\n  }\'\n```\n\n## Tool Continuation\n\nWhen the agent calls external tools, you\'ll receive a `tool-request` event. Execute the tools and send results back:\n\n```json\n{\n  "triggerName": "user-message",\n  "input": { "USER_MESSAGE": "..." },\n  "toolResults": [\n    {\n      "toolCallId": "tc_123",\n      "toolName": "get-user-account",\n      "result": {\n        "name": "Demo User",\n        "email": "demo@example.com"\n      }\n    }\n  ]\n}\n```\n\nThe Server SDK handles this continuation pattern automatically.\n\n## Upload URLs\n\nGet presigned URLs for file uploads. Files are uploaded directly to S3.\n\n```\nPOST /api/files/upload-urls\n```\n\n### Request Body\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def",\n  "files": [\n    {\n      "filename": "photo.jpg",\n      "mediaType": "image/jpeg",\n      "size": 102400\n    }\n  ]\n}\n```\n\n| Field               | Type   | Required | Description                         |\n| ------------------- | ------ | -------- | ----------------------------------- |\n| `sessionId`         | string | Yes      | Session ID to associate files with  |\n| `files`             | array  | Yes      | Array of file metadata (1-20 files) |\n| `files[].filename`  | string | Yes      | Original filename                   |\n| `files[].mediaType` | string | Yes      | MIME type (e.g., `image/png`)       |\n| `files[].size`      | number | Yes      | File size in bytes                  |\n\n### Response\n\n```json\n{\n  "files": [\n    {\n      "id": "file-abc123",\n      "uploadUrl": "https://s3.amazonaws.com/bucket/key?...",\n      "downloadUrl": "https://s3.amazonaws.com/bucket/key?..."\n    }\n  ]\n}\n```\n\n### Upload Flow\n\n1. Request upload URLs from the platform\n2. PUT file content to `uploadUrl` with `Content-Type` header\n3. Use `downloadUrl` as the `url` in `FileReference`\n4. Include `FileReference` in trigger input\n\n### Supported Types\n\n| Category  | Media Types                                                          |\n| --------- | -------------------------------------------------------------------- |\n| Images    | `image/jpeg`, `image/png`, `image/gif`, `image/webp`                 |\n| Documents | `application/pdf`, `text/plain`, `text/markdown`, `application/json` |\n\n### Limits\n\n| Limit                 | Value      |\n| --------------------- | ---------- |\n| Max file size         | 10 MB      |\n| Max total per request | 50 MB      |\n| Max files per request | 20         |\n| Upload URL expiry     | 15 minutes |\n| Download URL expiry   | 24 hours   |\n',
-    excerpt: "Sessions API Sessions represent conversations with agents. They store conversation history, resources, and variables.  Create Session Create a new agent session.  Request Body | Field     | Type   |...",
+    content: '\n# Sessions API\n\nSessions represent conversations with agents. They store conversation history, resources, and variables.\n\nAll session endpoints require an API key with the **Sessions** permission.\n\n## Create Session\n\nCreate a new agent session.\n\n```\nPOST /api/agent-sessions\n```\n\n### Request Body\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "input": {\n    "COMPANY_NAME": "Acme Corp",\n    "PRODUCT_NAME": "Widget Pro",\n    "USER_ID": "user-123"\n  }\n}\n```\n\n| Field     | Type   | Required | Description                           |\n| --------- | ------ | -------- | ------------------------------------- |\n| `agentId` | string | Yes      | Agent ID (the `id` field, not `slug`) |\n| `input`   | object | No       | Input variables for the agent         |\n\n> **Getting the agent ID:** Copy the ID from the agent URL in the [platform](https://octavus.ai) (e.g., `octavus.ai/agents/clxyz123`), or use the [CLI](/docs/server-sdk/cli) (`octavus sync ./agents/my-agent`) for local development workflows.\n\n### Response\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agent-sessions \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "agentId": "cm5xvz7k80001abcd",\n    "input": {\n      "COMPANY_NAME": "Acme Corp",\n      "PRODUCT_NAME": "Widget Pro"\n    }\n  }\'\n```\n\n## Get Session\n\nRetrieve session state. Returns UI-ready messages for active sessions, or expiration info for expired sessions.\n\n```\nGET /api/agent-sessions/:sessionId\n```\n\n### Query Parameters\n\n| Parameter | Type   | Description                                          |\n| --------- | ------ | ---------------------------------------------------- |\n| `format`  | string | Optional. Use `format=ui` for UI-ready messages only |\n\n### Response (Active Session)\n\nWhen the session is active, the response includes `UIMessage` objects:\n\n```json\n{\n  "id": "cm5xyz123abc456def",\n  "agentId": "cm5xvz7k80001abcd",\n  "status": "active",\n  "input": {\n    "COMPANY_NAME": "Acme Corp",\n    "PRODUCT_NAME": "Widget Pro"\n  },\n  "variables": {},\n  "resources": {\n    "CONVERSATION_SUMMARY": ""\n  },\n  "messages": [\n    {\n      "id": "1702345800000-xyz789a",\n      "role": "user",\n      "parts": [{ "type": "text", "text": "How do I reset my password?", "status": "done" }],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:00.000Z"\n    },\n    {\n      "id": "1702345805000-def456b",\n      "role": "assistant",\n      "parts": [\n        { "type": "text", "text": "I can help you reset your password...", "status": "done" }\n      ],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:05.000Z"\n    }\n  ],\n  "createdAt": "2024-01-15T10:30:00Z",\n  "updatedAt": "2024-01-15T10:30:05Z"\n}\n```\n\n### Response (Expired Session)\n\nWhen the session has expired, the response indicates the expiration status:\n\n```json\n{\n  "status": "expired",\n  "sessionId": "cm5xyz123abc456def",\n  "agentId": "cm5xvz7k80001abcd",\n  "createdAt": "2024-01-15T10:30:00Z"\n}\n```\n\nUse the [Restore Session](#restore-session) endpoint to restore an expired session from stored messages.\n\n````\n\n### UIMessage Parts\n\nMessages contain typed `parts` that preserve content ordering:\n\n| Part Type | Description |\n|-----------|-------------|\n| `text` | Text content with `text` and `status` fields |\n| `reasoning` | Extended reasoning with `text` and `status` fields |\n| `tool-call` | Tool execution with `toolCallId`, `toolName`, `displayName`, `args`, `result`, `status` |\n| `operation` | Internal operations with `operationId`, `name`, `operationType`, `status` |\n| `file` | File attachment with `id`, `mediaType`, `url`, `filename`, `size` |\n| `source` | Source reference with `sourceType`, `id`, `url`, `title` |\n| `object` | Structured output with `id`, `typeName`, `object`, `status` |\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agent-sessions/:sessionId \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n````\n\n## Restore Session\n\nRestore an expired session from stored messages. This allows you to continue a conversation after the server-side state has expired.\n\n```\nPOST /api/agent-sessions/:sessionId/restore\n```\n\n### Request Body\n\n```json\n{\n  "messages": [\n    {\n      "id": "1702345800000-xyz789a",\n      "role": "user",\n      "parts": [{ "type": "text", "text": "How do I reset my password?", "status": "done" }],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:00.000Z"\n    }\n  ],\n  "input": {\n    "COMPANY_NAME": "Acme Corp"\n  }\n}\n```\n\n| Field      | Type        | Required | Description                                                    |\n| ---------- | ----------- | -------- | -------------------------------------------------------------- |\n| `messages` | UIMessage[] | Yes      | Previously stored chat history                                 |\n| `input`    | object      | No       | Session input for system prompt interpolation (same as create) |\n\n### Response\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def",\n  "restored": true\n}\n```\n\n| Field       | Type    | Description                                                             |\n| ----------- | ------- | ----------------------------------------------------------------------- |\n| `sessionId` | string  | The session ID                                                          |\n| `restored`  | boolean | `true` if restored from messages, `false` if session was already active |\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agent-sessions/:sessionId/restore \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "messages": [...],\n    "input": { "COMPANY_NAME": "Acme Corp" }\n  }\'\n```\n\n> **Note**: Store the `UIMessage[]` array after each interaction to enable restoration. The restore endpoint reconstructs the conversation state from these messages.\n\n## Trigger Session\n\nExecute a trigger on a session. Returns a Server-Sent Events stream.\n\n```\nPOST /api/agent-sessions/:sessionId/trigger\n```\n\n### Request Body\n\n```json\n{\n  "triggerName": "user-message",\n  "input": {\n    "USER_MESSAGE": "How do I reset my password?"\n  },\n  "toolResults": []\n}\n```\n\n| Field         | Type   | Required | Description                                    |\n| ------------- | ------ | -------- | ---------------------------------------------- |\n| `triggerName` | string | Yes      | Name of the trigger to execute                 |\n| `input`       | object | No       | Input variables for the trigger                |\n| `toolResults` | array  | No       | Tool results for continuation (handled by SDK) |\n\n### Response\n\nReturns `text/event-stream` with SSE events:\n\n```\ndata: {"type":"start","messageId":"msg-123"}\n\ndata: {"type":"block-start","blockId":"b1","blockName":"Add user message","blockType":"add-message","display":"hidden"}\n\ndata: {"type":"block-end","blockId":"b1"}\n\ndata: {"type":"block-start","blockId":"b2","blockName":"Respond to user","blockType":"next-message","display":"stream","outputToChat":true}\n\ndata: {"type":"text-start","id":"t1"}\n\ndata: {"type":"text-delta","id":"t1","delta":"I"}\n\ndata: {"type":"text-delta","id":"t1","delta":" can"}\n\ndata: {"type":"text-delta","id":"t1","delta":" help"}\n\ndata: {"type":"text-delta","id":"t1","delta":" you"}\n\ndata: {"type":"text-delta","id":"t1","delta":" reset"}\n\ndata: {"type":"text-delta","id":"t1","delta":" your"}\n\ndata: {"type":"text-delta","id":"t1","delta":" password"}\n\ndata: {"type":"text-delta","id":"t1","delta":"!"}\n\ndata: {"type":"text-end","id":"t1"}\n\ndata: {"type":"block-end","blockId":"b2"}\n\ndata: {"type":"finish","finishReason":"stop"}\n\ndata: [DONE]\n```\n\n### Event Types\n\n| Event                   | Description                        |\n| ----------------------- | ---------------------------------- |\n| `start`                 | Stream started                     |\n| `finish`                | Execution complete                 |\n| `error`                 | Error occurred                     |\n| `block-start`           | Execution block started            |\n| `block-end`             | Execution block completed          |\n| `text-start`            | Text generation started            |\n| `text-delta`            | Incremental text content           |\n| `text-end`              | Text generation ended              |\n| `reasoning-start`       | Extended reasoning started         |\n| `reasoning-delta`       | Reasoning content                  |\n| `reasoning-end`         | Extended reasoning ended           |\n| `tool-input-start`      | Tool call initiated                |\n| `tool-input-delta`      | Tool arguments streaming           |\n| `tool-input-end`        | Tool arguments streaming ended     |\n| `tool-input-available`  | Tool input complete                |\n| `tool-output-available` | Tool completed with result         |\n| `tool-output-error`     | Tool failed                        |\n| `tool-request`          | Platform requesting tool execution |\n| `file-available`        | File ready for display/download    |\n| `resource-update`       | Resource value changed             |\n\n### Example\n\n```bash\ncurl -N -X POST https://octavus.ai/api/agent-sessions/:sessionId/trigger \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "triggerName": "user-message",\n    "input": { "USER_MESSAGE": "How do I reset my password?" }\n  }\'\n```\n\n## Tool Continuation\n\nWhen the agent calls external tools, you\'ll receive a `tool-request` event. Execute the tools and send results back:\n\n```json\n{\n  "triggerName": "user-message",\n  "input": { "USER_MESSAGE": "..." },\n  "toolResults": [\n    {\n      "toolCallId": "tc_123",\n      "toolName": "get-user-account",\n      "result": {\n        "name": "Demo User",\n        "email": "demo@example.com"\n      }\n    }\n  ]\n}\n```\n\nThe Server SDK handles this continuation pattern automatically.\n\n## Upload URLs\n\nGet presigned URLs for file uploads. Files are uploaded directly to S3.\n\n```\nPOST /api/files/upload-urls\n```\n\n### Request Body\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def",\n  "files": [\n    {\n      "filename": "photo.jpg",\n      "mediaType": "image/jpeg",\n      "size": 102400\n    }\n  ]\n}\n```\n\n| Field               | Type   | Required | Description                         |\n| ------------------- | ------ | -------- | ----------------------------------- |\n| `sessionId`         | string | Yes      | Session ID to associate files with  |\n| `files`             | array  | Yes      | Array of file metadata (1-20 files) |\n| `files[].filename`  | string | Yes      | Original filename                   |\n| `files[].mediaType` | string | Yes      | MIME type (e.g., `image/png`)       |\n| `files[].size`      | number | Yes      | File size in bytes                  |\n\n### Response\n\n```json\n{\n  "files": [\n    {\n      "id": "file-abc123",\n      "uploadUrl": "https://s3.amazonaws.com/bucket/key?...",\n      "downloadUrl": "https://s3.amazonaws.com/bucket/key?..."\n    }\n  ]\n}\n```\n\n### Upload Flow\n\n1. Request upload URLs from the platform\n2. PUT file content to `uploadUrl` with `Content-Type` header\n3. Use `downloadUrl` as the `url` in `FileReference`\n4. Include `FileReference` in trigger input\n\n### Supported Types\n\n| Category  | Media Types                                                          |\n| --------- | -------------------------------------------------------------------- |\n| Images    | `image/jpeg`, `image/png`, `image/gif`, `image/webp`                 |\n| Documents | `application/pdf`, `text/plain`, `text/markdown`, `application/json` |\n\n### Limits\n\n| Limit                 | Value      |\n| --------------------- | ---------- |\n| Max file size         | 10 MB      |\n| Max total per request | 50 MB      |\n| Max files per request | 20         |\n| Upload URL expiry     | 15 minutes |\n| Download URL expiry   | 24 hours   |\n',
+    excerpt: "Sessions API Sessions represent conversations with agents. They store conversation history, resources, and variables. All session endpoints require an API key with the Sessions permission.  Create...",
     order: 2
   },
   {
@@ -257,8 +257,8 @@ var docs_default = [
     section: "api-reference",
     title: "Agents",
     description: "Agent management API endpoints.",
-    content: '\n# Agents API\n\nManage agent definitions including protocols and prompts.\n\n## List Agents\n\nGet all agents in the project.\n\n```\nGET /api/agents\n```\n\n### Response\n\n```json\n{\n  "agents": [\n    {\n      "id": "cm5xvz7k80001abcd",\n      "slug": "support-chat",\n      "name": "Support Chat",\n      "description": "Customer support agent",\n      "format": "interactive",\n      "createdAt": "2024-01-10T08:00:00Z",\n      "updatedAt": "2024-01-15T10:00:00Z"\n    }\n  ]\n}\n```\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agents \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n## Get Agent\n\nGet a single agent by ID.\n\n```\nGET /api/agents/:id\n```\n\n### Response\n\n```json\n{\n  "id": "cm5xvz7k80001abcd",\n  "settings": {\n    "slug": "support-chat",\n    "name": "Support Chat",\n    "description": "Customer support agent",\n    "format": "interactive"\n  },\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "You are a support agent for {{COMPANY_NAME}}..."\n    },\n    {\n      "name": "user-message",\n      "content": "{{USER_MESSAGE}}"\n    }\n  ]\n}\n```\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agents/:agentId \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n> **Tip:** You can also view and edit agents directly in the [platform](https://octavus.ai), or use the [CLI](/docs/server-sdk/cli) (`octavus list`) for local workflows.\n\n## Create Agent\n\nCreate a new agent.\n\n```\nPOST /api/agents\n```\n\n### Request Body\n\n```json\n{\n  "settings": {\n    "slug": "support-chat",\n    "name": "Support Chat",\n    "description": "Customer support agent",\n    "format": "interactive"\n  },\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "You are a support agent..."\n    }\n  ]\n}\n```\n\n| Field                  | Type   | Required | Description               |\n| ---------------------- | ------ | -------- | ------------------------- |\n| `settings.slug`        | string | Yes      | URL-safe identifier       |\n| `settings.name`        | string | Yes      | Display name              |\n| `settings.description` | string | No       | Agent description         |\n| `settings.format`      | string | Yes      | `interactive` or `worker` |\n| `protocol`             | string | Yes      | YAML protocol definition  |\n| `prompts`              | array  | Yes      | Prompt files              |\n\n### Response\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "message": "Agent created successfully"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agents \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "settings": {\n      "slug": "my-agent",\n      "name": "My Agent",\n      "format": "interactive"\n    },\n    "protocol": "agent:\\n  model: anthropic/claude-sonnet-4-5\\n  system: system",\n    "prompts": [\n      { "name": "system", "content": "You are a helpful assistant." }\n    ]\n  }\'\n```\n\n## Update Agent\n\nUpdate an existing agent.\n\n```\nPATCH /api/agents/:id\n```\n\n### Request Body\n\n```json\n{\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "Updated system prompt..."\n    }\n  ]\n}\n```\n\nAll fields are optional. Only provided fields are updated.\n\n### Response\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "message": "Agent updated successfully"\n}\n```\n\n### Example\n\n```bash\ncurl -X PATCH https://octavus.ai/api/agents/:agentId \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "protocol": "agent:\\n  model: anthropic/claude-sonnet-4-5\\n  system: system\\n  thinking: high"\n  }\'\n```\n\n## Creating and Managing Agents\n\nThere are two ways to manage agents:\n\n### Platform UI\n\nCreate and edit agents directly at [octavus.ai](https://octavus.ai). The web editor provides real-time validation and is the easiest way to get started. Copy the agent ID from the URL to use in your application.\n\n### CLI (Local Development)\n\nFor version-controlled agent definitions, use the [Octavus CLI](/docs/server-sdk/cli):\n\n```bash\noctavus sync ./agents/support-chat\n```\n\nThis creates the agent if it doesn\'t exist, or updates it if it does. The CLI outputs the agent ID which you should store in an environment variable.\n\nFor CI/CD integration, see the [CLI documentation](/docs/server-sdk/cli#cicd-integration).\n',
-    excerpt: "Agents API Manage agent definitions including protocols and prompts.  List Agents Get all agents in the project.  Response  Example  Get Agent Get a single agent by ID.  Response  Example > Tip: You...",
+    content: '\n# Agents API\n\nManage agent definitions including protocols and prompts.\n\n## Permissions\n\n| Endpoint               | Method | Permission Required |\n| ---------------------- | ------ | ------------------- |\n| `/api/agents`          | GET    | Agents OR Sessions  |\n| `/api/agents/:id`      | GET    | Agents OR Sessions  |\n| `/api/agents`          | POST   | Agents              |\n| `/api/agents/:id`      | PATCH  | Agents              |\n| `/api/agents/validate` | POST   | Agents              |\n\nRead endpoints work with either permission since both the CLI (for sync) and Server SDK (for sessions) need to read agent definitions.\n\n## List Agents\n\nGet all agents in the project.\n\n```\nGET /api/agents\n```\n\n### Response\n\n```json\n{\n  "agents": [\n    {\n      "id": "cm5xvz7k80001abcd",\n      "slug": "support-chat",\n      "name": "Support Chat",\n      "description": "Customer support agent",\n      "format": "interactive",\n      "createdAt": "2024-01-10T08:00:00Z",\n      "updatedAt": "2024-01-15T10:00:00Z"\n    }\n  ]\n}\n```\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agents \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n## Get Agent\n\nGet a single agent by ID.\n\n```\nGET /api/agents/:id\n```\n\n### Response\n\n```json\n{\n  "id": "cm5xvz7k80001abcd",\n  "settings": {\n    "slug": "support-chat",\n    "name": "Support Chat",\n    "description": "Customer support agent",\n    "format": "interactive"\n  },\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "You are a support agent for {{COMPANY_NAME}}..."\n    },\n    {\n      "name": "user-message",\n      "content": "{{USER_MESSAGE}}"\n    }\n  ]\n}\n```\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agents/:agentId \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n> **Tip:** You can also view and edit agents directly in the [platform](https://octavus.ai), or use the [CLI](/docs/server-sdk/cli) (`octavus list`) for local workflows.\n\n## Create Agent\n\nCreate a new agent.\n\n```\nPOST /api/agents\n```\n\n### Request Body\n\n```json\n{\n  "settings": {\n    "slug": "support-chat",\n    "name": "Support Chat",\n    "description": "Customer support agent",\n    "format": "interactive"\n  },\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "You are a support agent..."\n    }\n  ]\n}\n```\n\n| Field                  | Type   | Required | Description               |\n| ---------------------- | ------ | -------- | ------------------------- |\n| `settings.slug`        | string | Yes      | URL-safe identifier       |\n| `settings.name`        | string | Yes      | Display name              |\n| `settings.description` | string | No       | Agent description         |\n| `settings.format`      | string | Yes      | `interactive` or `worker` |\n| `protocol`             | string | Yes      | YAML protocol definition  |\n| `prompts`              | array  | Yes      | Prompt files              |\n\n### Response\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "message": "Agent created successfully"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agents \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "settings": {\n      "slug": "my-agent",\n      "name": "My Agent",\n      "format": "interactive"\n    },\n    "protocol": "agent:\\n  model: anthropic/claude-sonnet-4-5\\n  system: system",\n    "prompts": [\n      { "name": "system", "content": "You are a helpful assistant." }\n    ]\n  }\'\n```\n\n## Update Agent\n\nUpdate an existing agent.\n\n```\nPATCH /api/agents/:id\n```\n\n### Request Body\n\n```json\n{\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "Updated system prompt..."\n    }\n  ]\n}\n```\n\nAll fields are optional. Only provided fields are updated.\n\n### Response\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "message": "Agent updated successfully"\n}\n```\n\n### Example\n\n```bash\ncurl -X PATCH https://octavus.ai/api/agents/:agentId \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "protocol": "agent:\\n  model: anthropic/claude-sonnet-4-5\\n  system: system\\n  thinking: high"\n  }\'\n```\n\n## Creating and Managing Agents\n\nThere are two ways to manage agents:\n\n### Platform UI\n\nCreate and edit agents directly at [octavus.ai](https://octavus.ai). The web editor provides real-time validation and is the easiest way to get started. Copy the agent ID from the URL to use in your application.\n\n### CLI (Local Development)\n\nFor version-controlled agent definitions, use the [Octavus CLI](/docs/server-sdk/cli):\n\n```bash\noctavus sync ./agents/support-chat\n```\n\nThis creates the agent if it doesn\'t exist, or updates it if it does. The CLI outputs the agent ID which you should store in an environment variable.\n\nFor CI/CD integration, see the [CLI documentation](/docs/server-sdk/cli#cicd-integration).\n',
+    excerpt: "Agents API Manage agent definitions including protocols and prompts.  Permissions | Endpoint               | Method | Permission Required | | ---------------------- | ------ | ------------------- | |...",
     order: 3
   },
   {
@@ -365,7 +365,7 @@ var sections_default = [
         section: "server-sdk",
         title: "CLI",
         description: "Command-line interface for validating and syncing agent definitions.",
-        content: '\n# Octavus CLI\n\nThe `@octavus/cli` package provides a command-line interface for validating and syncing agent definitions from your local filesystem to the Octavus platform.\n\n**Current version:** `1.0.0`\n\n## Installation\n\n```bash\nnpm install --save-dev @octavus/cli\n```\n\n## Configuration\n\nThe CLI requires an API key with agent management permissions.\n\n### Environment Variables\n\n| Variable              | Description                                             |\n| --------------------- | ------------------------------------------------------- |\n| `OCTAVUS_CLI_API_KEY` | API key with agent management permissions (recommended) |\n| `OCTAVUS_API_KEY`     | Fallback if `OCTAVUS_CLI_API_KEY` not set               |\n| `OCTAVUS_API_URL`     | Optional, defaults to `https://octavus.ai`              |\n\n### Two-Key Strategy (Recommended)\n\nFor production deployments, use separate API keys:\n\n```bash\n# CI/CD or .env.local (not committed)\nOCTAVUS_CLI_API_KEY=oct_sk_...  # Agent management permissions\n\n# Production .env\nOCTAVUS_API_KEY=oct_sk_...      # Session-only permissions\n```\n\nThis ensures production servers only have session permissions (smaller blast radius if leaked), while agent management is restricted to development/CI environments.\n\n### Multiple Environments\n\nUse separate Octavus projects for staging and production, each with their own API keys. The `--env` flag lets you load different environment files:\n\n```bash\n# Local development (default: .env)\noctavus sync ./agents/my-agent\n\n# Staging project\noctavus --env .env.staging sync ./agents/my-agent\n\n# Production project\noctavus --env .env.production sync ./agents/my-agent\n```\n\nExample environment files:\n\n```bash\n# .env.staging (syncs to your staging project)\nOCTAVUS_CLI_API_KEY=oct_sk_staging_project_key...\n\n# .env.production (syncs to your production project)\nOCTAVUS_CLI_API_KEY=oct_sk_production_project_key...\n```\n\nEach project has its own agents, so you\'ll get different agent IDs per environment.\n\n## Global Options\n\n| Option         | Description                                             |\n| -------------- | ------------------------------------------------------- |\n| `--env <file>` | Load environment from a specific file (default: `.env`) |\n| `--help`       | Show help                                               |\n| `--version`    | Show version                                            |\n\n## Commands\n\n### `octavus sync <path>`\n\nSync an agent definition to the platform. Creates the agent if it doesn\'t exist, or updates it if it does.\n\n```bash\noctavus sync ./agents/my-agent\n```\n\n**Options:**\n\n- `--json` \u2014 Output as JSON (for CI/CD parsing)\n- `--quiet` \u2014 Suppress non-essential output\n\n**Example output:**\n\n```\n\u2139 Reading agent from ./agents/my-agent...\n\u2139 Syncing support-chat...\n\u2713 Created: support-chat\n  Agent ID: clxyz123abc456\n```\n\n### `octavus validate <path>`\n\nValidate an agent definition without saving. Useful for CI/CD pipelines.\n\n```bash\noctavus validate ./agents/my-agent\n```\n\n**Exit codes:**\n\n- `0` \u2014 Validation passed\n- `1` \u2014 Validation errors\n- `2` \u2014 Configuration errors (missing API key, etc.)\n\n### `octavus list`\n\nList all agents in your project.\n\n```bash\noctavus list\n```\n\n**Example output:**\n\n```\nSLUG                  NAME                            FORMAT        ID\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nsupport-chat          Support Chat Agent              interactive   clxyz123abc456\n\n1 agent(s)\n```\n\n### `octavus get <slug>`\n\nGet details about a specific agent by its slug.\n\n```bash\noctavus get support-chat\n```\n\n## Agent Directory Structure\n\nThe CLI expects agent definitions in a specific directory structure:\n\n```\nmy-agent/\n\u251C\u2500\u2500 settings.json     # Required: Agent metadata\n\u251C\u2500\u2500 protocol.yaml     # Required: Agent protocol\n\u2514\u2500\u2500 prompts/          # Optional: Prompt templates\n    \u251C\u2500\u2500 system.md\n    \u2514\u2500\u2500 user-message.md\n```\n\n### settings.json\n\n```json\n{\n  "slug": "my-agent",\n  "name": "My Agent",\n  "description": "A helpful assistant",\n  "format": "interactive"\n}\n```\n\n### protocol.yaml\n\nSee the [Protocol documentation](/docs/protocol/overview) for details on protocol syntax.\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Validate and Sync Agents\n\non:\n  push:\n    branches: [main]\n    paths:\n      - \'agents/**\'\n\njobs:\n  sync:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \'22\'\n\n      - run: npm install\n\n      - name: Validate agent\n        run: npx octavus validate ./agents/support-chat\n        env:\n          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}\n\n      - name: Sync agent\n        run: npx octavus sync ./agents/support-chat\n        env:\n          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}\n```\n\n### Package.json Scripts\n\nAdd sync scripts to your `package.json`:\n\n```json\n{\n  "scripts": {\n    "agents:validate": "octavus validate ./agents/my-agent",\n    "agents:sync": "octavus sync ./agents/my-agent"\n  },\n  "devDependencies": {\n    "@octavus/cli": "^0.1.0"\n  }\n}\n```\n\n## Workflow\n\nThe recommended workflow for managing agents:\n\n1. **Define agent locally** \u2014 Create `settings.json`, `protocol.yaml`, and prompts\n2. **Validate** \u2014 Run `octavus validate ./my-agent` to check for errors\n3. **Sync** \u2014 Run `octavus sync ./my-agent` to push to platform\n4. **Store agent ID** \u2014 Save the output ID in an environment variable\n5. **Use in app** \u2014 Read the ID from env and pass to `client.agentSessions.create()`\n\n```bash\n# After syncing: octavus sync ./agents/support-chat\n# Output: Agent ID: clxyz123abc456\n\n# Add to your .env file\nOCTAVUS_SUPPORT_AGENT_ID=clxyz123abc456\n```\n\n```typescript\nconst agentId = process.env.OCTAVUS_SUPPORT_AGENT_ID;\n\nconst sessionId = await client.agentSessions.create(agentId, {\n  COMPANY_NAME: \'Acme Corp\',\n});\n```\n',
+        content: '\n# Octavus CLI\n\nThe `@octavus/cli` package provides a command-line interface for validating and syncing agent definitions from your local filesystem to the Octavus platform.\n\n**Current version:** `1.0.0`\n\n## Installation\n\n```bash\nnpm install --save-dev @octavus/cli\n```\n\n## Configuration\n\nThe CLI requires an API key with the **Agents** permission.\n\n### Environment Variables\n\n| Variable              | Description                                    |\n| --------------------- | ---------------------------------------------- |\n| `OCTAVUS_CLI_API_KEY` | API key with "Agents" permission (recommended) |\n| `OCTAVUS_API_KEY`     | Fallback if `OCTAVUS_CLI_API_KEY` not set      |\n| `OCTAVUS_API_URL`     | Optional, defaults to `https://octavus.ai`     |\n\n### Two-Key Strategy (Recommended)\n\nFor production deployments, use separate API keys with minimal permissions:\n\n```bash\n# CI/CD or .env.local (not committed)\nOCTAVUS_CLI_API_KEY=oct_sk_...  # "Agents" permission only\n\n# Production .env\nOCTAVUS_API_KEY=oct_sk_...      # "Sessions" permission only\n```\n\nThis ensures production servers only have session permissions (smaller blast radius if leaked), while agent management is restricted to development/CI environments.\n\n### Multiple Environments\n\nUse separate Octavus projects for staging and production, each with their own API keys. The `--env` flag lets you load different environment files:\n\n```bash\n# Local development (default: .env)\noctavus sync ./agents/my-agent\n\n# Staging project\noctavus --env .env.staging sync ./agents/my-agent\n\n# Production project\noctavus --env .env.production sync ./agents/my-agent\n```\n\nExample environment files:\n\n```bash\n# .env.staging (syncs to your staging project)\nOCTAVUS_CLI_API_KEY=oct_sk_staging_project_key...\n\n# .env.production (syncs to your production project)\nOCTAVUS_CLI_API_KEY=oct_sk_production_project_key...\n```\n\nEach project has its own agents, so you\'ll get different agent IDs per environment.\n\n## Global Options\n\n| Option         | Description                                             |\n| -------------- | ------------------------------------------------------- |\n| `--env <file>` | Load environment from a specific file (default: `.env`) |\n| `--help`       | Show help                                               |\n| `--version`    | Show version                                            |\n\n## Commands\n\n### `octavus sync <path>`\n\nSync an agent definition to the platform. Creates the agent if it doesn\'t exist, or updates it if it does.\n\n```bash\noctavus sync ./agents/my-agent\n```\n\n**Options:**\n\n- `--json` \u2014 Output as JSON (for CI/CD parsing)\n- `--quiet` \u2014 Suppress non-essential output\n\n**Example output:**\n\n```\n\u2139 Reading agent from ./agents/my-agent...\n\u2139 Syncing support-chat...\n\u2713 Created: support-chat\n  Agent ID: clxyz123abc456\n```\n\n### `octavus validate <path>`\n\nValidate an agent definition without saving. Useful for CI/CD pipelines.\n\n```bash\noctavus validate ./agents/my-agent\n```\n\n**Exit codes:**\n\n- `0` \u2014 Validation passed\n- `1` \u2014 Validation errors\n- `2` \u2014 Configuration errors (missing API key, etc.)\n\n### `octavus list`\n\nList all agents in your project.\n\n```bash\noctavus list\n```\n\n**Example output:**\n\n```\nSLUG                  NAME                            FORMAT        ID\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nsupport-chat          Support Chat Agent              interactive   clxyz123abc456\n\n1 agent(s)\n```\n\n### `octavus get <slug>`\n\nGet details about a specific agent by its slug.\n\n```bash\noctavus get support-chat\n```\n\n## Agent Directory Structure\n\nThe CLI expects agent definitions in a specific directory structure:\n\n```\nmy-agent/\n\u251C\u2500\u2500 settings.json     # Required: Agent metadata\n\u251C\u2500\u2500 protocol.yaml     # Required: Agent protocol\n\u2514\u2500\u2500 prompts/          # Optional: Prompt templates\n    \u251C\u2500\u2500 system.md\n    \u2514\u2500\u2500 user-message.md\n```\n\n### settings.json\n\n```json\n{\n  "slug": "my-agent",\n  "name": "My Agent",\n  "description": "A helpful assistant",\n  "format": "interactive"\n}\n```\n\n### protocol.yaml\n\nSee the [Protocol documentation](/docs/protocol/overview) for details on protocol syntax.\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Validate and Sync Agents\n\non:\n  push:\n    branches: [main]\n    paths:\n      - \'agents/**\'\n\njobs:\n  sync:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \'22\'\n\n      - run: npm install\n\n      - name: Validate agent\n        run: npx octavus validate ./agents/support-chat\n        env:\n          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}\n\n      - name: Sync agent\n        run: npx octavus sync ./agents/support-chat\n        env:\n          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}\n```\n\n### Package.json Scripts\n\nAdd sync scripts to your `package.json`:\n\n```json\n{\n  "scripts": {\n    "agents:validate": "octavus validate ./agents/my-agent",\n    "agents:sync": "octavus sync ./agents/my-agent"\n  },\n  "devDependencies": {\n    "@octavus/cli": "^0.1.0"\n  }\n}\n```\n\n## Workflow\n\nThe recommended workflow for managing agents:\n\n1. **Define agent locally** \u2014 Create `settings.json`, `protocol.yaml`, and prompts\n2. **Validate** \u2014 Run `octavus validate ./my-agent` to check for errors\n3. **Sync** \u2014 Run `octavus sync ./my-agent` to push to platform\n4. **Store agent ID** \u2014 Save the output ID in an environment variable\n5. **Use in app** \u2014 Read the ID from env and pass to `client.agentSessions.create()`\n\n```bash\n# After syncing: octavus sync ./agents/support-chat\n# Output: Agent ID: clxyz123abc456\n\n# Add to your .env file\nOCTAVUS_SUPPORT_AGENT_ID=clxyz123abc456\n```\n\n```typescript\nconst agentId = process.env.OCTAVUS_SUPPORT_AGENT_ID;\n\nconst sessionId = await client.agentSessions.create(agentId, {\n  COMPANY_NAME: \'Acme Corp\',\n});\n```\n',
         excerpt: "Octavus CLI The  package provides a command-line interface for validating and syncing agent definitions from your local filesystem to the Octavus platform. Current version:   Installation ...",
         order: 5
       }
@@ -569,7 +569,7 @@ var sections_default = [
         section: "api-reference",
         title: "Overview",
         description: "REST API overview and authentication.",
-        content: '\n# API Reference\n\nThe Octavus API is a RESTful API that enables programmatic access to agent management and session execution.\n\n## Base URL\n\n```\nhttps://octavus.ai\n```\n\n## Authentication\n\nAll API requests require authentication using a Bearer token:\n\n```bash\ncurl -H "Authorization: Bearer YOUR_API_KEY" \\\n  https://octavus.ai/api/agents\n```\n\nAPI keys can be created in the Octavus Platform under your project\'s **API Keys** page.\n\n## Response Format\n\nAll responses are JSON. Success responses return the data directly (not wrapped in a `data` field).\n\n### Success Response\n\n```json\n{\n  "sessionId": "sess_abc123"\n}\n```\n\n### Error Response\n\n```json\n{\n  "error": {\n    "code": "NOT_FOUND",\n    "message": "Agent not found"\n  }\n}\n```\n\n## HTTP Status Codes\n\n| Code | Description                               |\n| ---- | ----------------------------------------- |\n| 200  | Success                                   |\n| 201  | Created                                   |\n| 400  | Bad Request - Invalid parameters          |\n| 401  | Unauthorized - Missing or invalid API key |\n| 403  | Forbidden - Insufficient permissions      |\n| 404  | Not Found                                 |\n| 500  | Internal Server Error                     |\n\n## Endpoints Overview\n\n### Agents\n\n| Method | Endpoint          | Description     |\n| ------ | ----------------- | --------------- |\n| GET    | `/api/agents`     | List all agents |\n| GET    | `/api/agents/:id` | Get agent by ID |\n| POST   | `/api/agents`     | Create agent    |\n| PATCH  | `/api/agents/:id` | Update agent    |\n\n### Sessions\n\n| Method | Endpoint                          | Description           |\n| ------ | --------------------------------- | --------------------- |\n| POST   | `/api/agent-sessions`             | Create session        |\n| GET    | `/api/agent-sessions/:id`         | Get session state     |\n| POST   | `/api/agent-sessions/:id/trigger` | Execute trigger (SSE) |\n\n## Streaming\n\nThe trigger endpoint returns Server-Sent Events (SSE):\n\n```bash\ncurl -N -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{"triggerName": "user-message", "input": {"USER_MESSAGE": "Hello"}}\' \\\n  https://octavus.ai/api/agent-sessions/SESSION_ID/trigger\n```\n\nResponse format:\n\n```\ndata: {"type":"start","messageId":"..."}\n\ndata: {"type":"block-start","blockId":"...","blockName":"Respond","blockType":"next-message","display":"stream"}\n\ndata: {"type":"text-start","id":"..."}\n\ndata: {"type":"text-delta","id":"...","delta":"Hello"}\n\ndata: {"type":"text-delta","id":"...","delta":"!"}\n\ndata: {"type":"text-end","id":"..."}\n\ndata: {"type":"block-end","blockId":"..."}\n\ndata: {"type":"finish","finishReason":"stop"}\n\ndata: [DONE]\n```\n\n## SDKs\n\nWe recommend using our SDKs instead of calling the API directly:\n\n- **Server SDK**: `@octavus/server-sdk` - For Node.js backends\n- **React SDK**: `@octavus/react` - For React applications\n- **Client SDK**: `@octavus/client-sdk` - For other frontend frameworks\n\nThe SDKs handle authentication, streaming, and tool execution automatically.\n',
+        content: '\n# API Reference\n\nThe Octavus API is a RESTful API that enables programmatic access to agent management and session execution.\n\n## Base URL\n\n```\nhttps://octavus.ai\n```\n\n## Authentication\n\nAll API requests require authentication using a Bearer token:\n\n```bash\ncurl -H "Authorization: Bearer YOUR_API_KEY" \\\n  https://octavus.ai/api/agents\n```\n\nAPI keys can be created in the Octavus Platform under your project\'s **API Keys** page.\n\n## API Key Permissions\n\nAPI keys have two permission scopes:\n\n| Permission   | Description                                              | Used By    |\n| ------------ | -------------------------------------------------------- | ---------- |\n| **Sessions** | Create and manage sessions, trigger agents, upload files | Server SDK |\n| **Agents**   | Create, update, and validate agent definitions           | CLI        |\n\nBoth permissions allow reading agent definitions (needed by CLI for sync and Server SDK for sessions).\n\n**Recommended setup:** Use separate API keys for different purposes:\n\n- **CLI key** with only "Agents" permission for CI/CD and development\n- **Server key** with only "Sessions" permission for production applications\n\nThis limits the blast radius if a key is compromised.\n\n## Response Format\n\nAll responses are JSON. Success responses return the data directly (not wrapped in a `data` field).\n\n### Success Response\n\n```json\n{\n  "sessionId": "sess_abc123"\n}\n```\n\n### Error Response\n\n```json\n{\n  "error": {\n    "code": "NOT_FOUND",\n    "message": "Agent not found"\n  }\n}\n```\n\n## HTTP Status Codes\n\n| Code | Description                               |\n| ---- | ----------------------------------------- |\n| 200  | Success                                   |\n| 201  | Created                                   |\n| 400  | Bad Request - Invalid parameters          |\n| 401  | Unauthorized - Missing or invalid API key |\n| 403  | Forbidden - Insufficient permissions      |\n| 404  | Not Found                                 |\n| 500  | Internal Server Error                     |\n\n## Endpoints Overview\n\n### Agents\n\n| Method | Endpoint          | Description     |\n| ------ | ----------------- | --------------- |\n| GET    | `/api/agents`     | List all agents |\n| GET    | `/api/agents/:id` | Get agent by ID |\n| POST   | `/api/agents`     | Create agent    |\n| PATCH  | `/api/agents/:id` | Update agent    |\n\n### Sessions\n\n| Method | Endpoint                          | Description           |\n| ------ | --------------------------------- | --------------------- |\n| POST   | `/api/agent-sessions`             | Create session        |\n| GET    | `/api/agent-sessions/:id`         | Get session state     |\n| POST   | `/api/agent-sessions/:id/trigger` | Execute trigger (SSE) |\n\n## Streaming\n\nThe trigger endpoint returns Server-Sent Events (SSE):\n\n```bash\ncurl -N -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{"triggerName": "user-message", "input": {"USER_MESSAGE": "Hello"}}\' \\\n  https://octavus.ai/api/agent-sessions/SESSION_ID/trigger\n```\n\nResponse format:\n\n```\ndata: {"type":"start","messageId":"..."}\n\ndata: {"type":"block-start","blockId":"...","blockName":"Respond","blockType":"next-message","display":"stream"}\n\ndata: {"type":"text-start","id":"..."}\n\ndata: {"type":"text-delta","id":"...","delta":"Hello"}\n\ndata: {"type":"text-delta","id":"...","delta":"!"}\n\ndata: {"type":"text-end","id":"..."}\n\ndata: {"type":"block-end","blockId":"..."}\n\ndata: {"type":"finish","finishReason":"stop"}\n\ndata: [DONE]\n```\n\n## SDKs\n\nWe recommend using our SDKs instead of calling the API directly:\n\n- **Server SDK**: `@octavus/server-sdk` - For Node.js backends\n- **React SDK**: `@octavus/react` - For React applications\n- **Client SDK**: `@octavus/client-sdk` - For other frontend frameworks\n\nThe SDKs handle authentication, streaming, and tool execution automatically.\n',
         excerpt: "API Reference The Octavus API is a RESTful API that enables programmatic access to agent management and session execution.  Base URL  Authentication All API requests require authentication using a...",
         order: 1
       },
@@ -578,8 +578,8 @@ var sections_default = [
         section: "api-reference",
         title: "Sessions",
         description: "Session management API endpoints.",
-        content: '\n# Sessions API\n\nSessions represent conversations with agents. They store conversation history, resources, and variables.\n\n## Create Session\n\nCreate a new agent session.\n\n```\nPOST /api/agent-sessions\n```\n\n### Request Body\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "input": {\n    "COMPANY_NAME": "Acme Corp",\n    "PRODUCT_NAME": "Widget Pro",\n    "USER_ID": "user-123"\n  }\n}\n```\n\n| Field     | Type   | Required | Description                           |\n| --------- | ------ | -------- | ------------------------------------- |\n| `agentId` | string | Yes      | Agent ID (the `id` field, not `slug`) |\n| `input`   | object | No       | Input variables for the agent         |\n\n> **Getting the agent ID:** Copy the ID from the agent URL in the [platform](https://octavus.ai) (e.g., `octavus.ai/agents/clxyz123`), or use the [CLI](/docs/server-sdk/cli) (`octavus sync ./agents/my-agent`) for local development workflows.\n\n### Response\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agent-sessions \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "agentId": "cm5xvz7k80001abcd",\n    "input": {\n      "COMPANY_NAME": "Acme Corp",\n      "PRODUCT_NAME": "Widget Pro"\n    }\n  }\'\n```\n\n## Get Session\n\nRetrieve session state. Returns UI-ready messages for active sessions, or expiration info for expired sessions.\n\n```\nGET /api/agent-sessions/:sessionId\n```\n\n### Query Parameters\n\n| Parameter | Type   | Description                                          |\n| --------- | ------ | ---------------------------------------------------- |\n| `format`  | string | Optional. Use `format=ui` for UI-ready messages only |\n\n### Response (Active Session)\n\nWhen the session is active, the response includes `UIMessage` objects:\n\n```json\n{\n  "id": "cm5xyz123abc456def",\n  "agentId": "cm5xvz7k80001abcd",\n  "status": "active",\n  "input": {\n    "COMPANY_NAME": "Acme Corp",\n    "PRODUCT_NAME": "Widget Pro"\n  },\n  "variables": {},\n  "resources": {\n    "CONVERSATION_SUMMARY": ""\n  },\n  "messages": [\n    {\n      "id": "1702345800000-xyz789a",\n      "role": "user",\n      "parts": [{ "type": "text", "text": "How do I reset my password?", "status": "done" }],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:00.000Z"\n    },\n    {\n      "id": "1702345805000-def456b",\n      "role": "assistant",\n      "parts": [\n        { "type": "text", "text": "I can help you reset your password...", "status": "done" }\n      ],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:05.000Z"\n    }\n  ],\n  "createdAt": "2024-01-15T10:30:00Z",\n  "updatedAt": "2024-01-15T10:30:05Z"\n}\n```\n\n### Response (Expired Session)\n\nWhen the session has expired, the response indicates the expiration status:\n\n```json\n{\n  "status": "expired",\n  "sessionId": "cm5xyz123abc456def",\n  "agentId": "cm5xvz7k80001abcd",\n  "createdAt": "2024-01-15T10:30:00Z"\n}\n```\n\nUse the [Restore Session](#restore-session) endpoint to restore an expired session from stored messages.\n\n````\n\n### UIMessage Parts\n\nMessages contain typed `parts` that preserve content ordering:\n\n| Part Type | Description |\n|-----------|-------------|\n| `text` | Text content with `text` and `status` fields |\n| `reasoning` | Extended reasoning with `text` and `status` fields |\n| `tool-call` | Tool execution with `toolCallId`, `toolName`, `displayName`, `args`, `result`, `status` |\n| `operation` | Internal operations with `operationId`, `name`, `operationType`, `status` |\n| `file` | File attachment with `id`, `mediaType`, `url`, `filename`, `size` |\n| `source` | Source reference with `sourceType`, `id`, `url`, `title` |\n| `object` | Structured output with `id`, `typeName`, `object`, `status` |\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agent-sessions/:sessionId \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n````\n\n## Restore Session\n\nRestore an expired session from stored messages. This allows you to continue a conversation after the server-side state has expired.\n\n```\nPOST /api/agent-sessions/:sessionId/restore\n```\n\n### Request Body\n\n```json\n{\n  "messages": [\n    {\n      "id": "1702345800000-xyz789a",\n      "role": "user",\n      "parts": [{ "type": "text", "text": "How do I reset my password?", "status": "done" }],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:00.000Z"\n    }\n  ],\n  "input": {\n    "COMPANY_NAME": "Acme Corp"\n  }\n}\n```\n\n| Field      | Type        | Required | Description                                                    |\n| ---------- | ----------- | -------- | -------------------------------------------------------------- |\n| `messages` | UIMessage[] | Yes      | Previously stored chat history                                 |\n| `input`    | object      | No       | Session input for system prompt interpolation (same as create) |\n\n### Response\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def",\n  "restored": true\n}\n```\n\n| Field       | Type    | Description                                                             |\n| ----------- | ------- | ----------------------------------------------------------------------- |\n| `sessionId` | string  | The session ID                                                          |\n| `restored`  | boolean | `true` if restored from messages, `false` if session was already active |\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agent-sessions/:sessionId/restore \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "messages": [...],\n    "input": { "COMPANY_NAME": "Acme Corp" }\n  }\'\n```\n\n> **Note**: Store the `UIMessage[]` array after each interaction to enable restoration. The restore endpoint reconstructs the conversation state from these messages.\n\n## Trigger Session\n\nExecute a trigger on a session. Returns a Server-Sent Events stream.\n\n```\nPOST /api/agent-sessions/:sessionId/trigger\n```\n\n### Request Body\n\n```json\n{\n  "triggerName": "user-message",\n  "input": {\n    "USER_MESSAGE": "How do I reset my password?"\n  },\n  "toolResults": []\n}\n```\n\n| Field         | Type   | Required | Description                                    |\n| ------------- | ------ | -------- | ---------------------------------------------- |\n| `triggerName` | string | Yes      | Name of the trigger to execute                 |\n| `input`       | object | No       | Input variables for the trigger                |\n| `toolResults` | array  | No       | Tool results for continuation (handled by SDK) |\n\n### Response\n\nReturns `text/event-stream` with SSE events:\n\n```\ndata: {"type":"start","messageId":"msg-123"}\n\ndata: {"type":"block-start","blockId":"b1","blockName":"Add user message","blockType":"add-message","display":"hidden"}\n\ndata: {"type":"block-end","blockId":"b1"}\n\ndata: {"type":"block-start","blockId":"b2","blockName":"Respond to user","blockType":"next-message","display":"stream","outputToChat":true}\n\ndata: {"type":"text-start","id":"t1"}\n\ndata: {"type":"text-delta","id":"t1","delta":"I"}\n\ndata: {"type":"text-delta","id":"t1","delta":" can"}\n\ndata: {"type":"text-delta","id":"t1","delta":" help"}\n\ndata: {"type":"text-delta","id":"t1","delta":" you"}\n\ndata: {"type":"text-delta","id":"t1","delta":" reset"}\n\ndata: {"type":"text-delta","id":"t1","delta":" your"}\n\ndata: {"type":"text-delta","id":"t1","delta":" password"}\n\ndata: {"type":"text-delta","id":"t1","delta":"!"}\n\ndata: {"type":"text-end","id":"t1"}\n\ndata: {"type":"block-end","blockId":"b2"}\n\ndata: {"type":"finish","finishReason":"stop"}\n\ndata: [DONE]\n```\n\n### Event Types\n\n| Event                   | Description                        |\n| ----------------------- | ---------------------------------- |\n| `start`                 | Stream started                     |\n| `finish`                | Execution complete                 |\n| `error`                 | Error occurred                     |\n| `block-start`           | Execution block started            |\n| `block-end`             | Execution block completed          |\n| `text-start`            | Text generation started            |\n| `text-delta`            | Incremental text content           |\n| `text-end`              | Text generation ended              |\n| `reasoning-start`       | Extended reasoning started         |\n| `reasoning-delta`       | Reasoning content                  |\n| `reasoning-end`         | Extended reasoning ended           |\n| `tool-input-start`      | Tool call initiated                |\n| `tool-input-delta`      | Tool arguments streaming           |\n| `tool-input-end`        | Tool arguments streaming ended     |\n| `tool-input-available`  | Tool input complete                |\n| `tool-output-available` | Tool completed with result         |\n| `tool-output-error`     | Tool failed                        |\n| `tool-request`          | Platform requesting tool execution |\n| `file-available`        | File ready for display/download    |\n| `resource-update`       | Resource value changed             |\n\n### Example\n\n```bash\ncurl -N -X POST https://octavus.ai/api/agent-sessions/:sessionId/trigger \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "triggerName": "user-message",\n    "input": { "USER_MESSAGE": "How do I reset my password?" }\n  }\'\n```\n\n## Tool Continuation\n\nWhen the agent calls external tools, you\'ll receive a `tool-request` event. Execute the tools and send results back:\n\n```json\n{\n  "triggerName": "user-message",\n  "input": { "USER_MESSAGE": "..." },\n  "toolResults": [\n    {\n      "toolCallId": "tc_123",\n      "toolName": "get-user-account",\n      "result": {\n        "name": "Demo User",\n        "email": "demo@example.com"\n      }\n    }\n  ]\n}\n```\n\nThe Server SDK handles this continuation pattern automatically.\n\n## Upload URLs\n\nGet presigned URLs for file uploads. Files are uploaded directly to S3.\n\n```\nPOST /api/files/upload-urls\n```\n\n### Request Body\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def",\n  "files": [\n    {\n      "filename": "photo.jpg",\n      "mediaType": "image/jpeg",\n      "size": 102400\n    }\n  ]\n}\n```\n\n| Field               | Type   | Required | Description                         |\n| ------------------- | ------ | -------- | ----------------------------------- |\n| `sessionId`         | string | Yes      | Session ID to associate files with  |\n| `files`             | array  | Yes      | Array of file metadata (1-20 files) |\n| `files[].filename`  | string | Yes      | Original filename                   |\n| `files[].mediaType` | string | Yes      | MIME type (e.g., `image/png`)       |\n| `files[].size`      | number | Yes      | File size in bytes                  |\n\n### Response\n\n```json\n{\n  "files": [\n    {\n      "id": "file-abc123",\n      "uploadUrl": "https://s3.amazonaws.com/bucket/key?...",\n      "downloadUrl": "https://s3.amazonaws.com/bucket/key?..."\n    }\n  ]\n}\n```\n\n### Upload Flow\n\n1. Request upload URLs from the platform\n2. PUT file content to `uploadUrl` with `Content-Type` header\n3. Use `downloadUrl` as the `url` in `FileReference`\n4. Include `FileReference` in trigger input\n\n### Supported Types\n\n| Category  | Media Types                                                          |\n| --------- | -------------------------------------------------------------------- |\n| Images    | `image/jpeg`, `image/png`, `image/gif`, `image/webp`                 |\n| Documents | `application/pdf`, `text/plain`, `text/markdown`, `application/json` |\n\n### Limits\n\n| Limit                 | Value      |\n| --------------------- | ---------- |\n| Max file size         | 10 MB      |\n| Max total per request | 50 MB      |\n| Max files per request | 20         |\n| Upload URL expiry     | 15 minutes |\n| Download URL expiry   | 24 hours   |\n',
-        excerpt: "Sessions API Sessions represent conversations with agents. They store conversation history, resources, and variables.  Create Session Create a new agent session.  Request Body | Field     | Type   |...",
+        content: '\n# Sessions API\n\nSessions represent conversations with agents. They store conversation history, resources, and variables.\n\nAll session endpoints require an API key with the **Sessions** permission.\n\n## Create Session\n\nCreate a new agent session.\n\n```\nPOST /api/agent-sessions\n```\n\n### Request Body\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "input": {\n    "COMPANY_NAME": "Acme Corp",\n    "PRODUCT_NAME": "Widget Pro",\n    "USER_ID": "user-123"\n  }\n}\n```\n\n| Field     | Type   | Required | Description                           |\n| --------- | ------ | -------- | ------------------------------------- |\n| `agentId` | string | Yes      | Agent ID (the `id` field, not `slug`) |\n| `input`   | object | No       | Input variables for the agent         |\n\n> **Getting the agent ID:** Copy the ID from the agent URL in the [platform](https://octavus.ai) (e.g., `octavus.ai/agents/clxyz123`), or use the [CLI](/docs/server-sdk/cli) (`octavus sync ./agents/my-agent`) for local development workflows.\n\n### Response\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agent-sessions \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "agentId": "cm5xvz7k80001abcd",\n    "input": {\n      "COMPANY_NAME": "Acme Corp",\n      "PRODUCT_NAME": "Widget Pro"\n    }\n  }\'\n```\n\n## Get Session\n\nRetrieve session state. Returns UI-ready messages for active sessions, or expiration info for expired sessions.\n\n```\nGET /api/agent-sessions/:sessionId\n```\n\n### Query Parameters\n\n| Parameter | Type   | Description                                          |\n| --------- | ------ | ---------------------------------------------------- |\n| `format`  | string | Optional. Use `format=ui` for UI-ready messages only |\n\n### Response (Active Session)\n\nWhen the session is active, the response includes `UIMessage` objects:\n\n```json\n{\n  "id": "cm5xyz123abc456def",\n  "agentId": "cm5xvz7k80001abcd",\n  "status": "active",\n  "input": {\n    "COMPANY_NAME": "Acme Corp",\n    "PRODUCT_NAME": "Widget Pro"\n  },\n  "variables": {},\n  "resources": {\n    "CONVERSATION_SUMMARY": ""\n  },\n  "messages": [\n    {\n      "id": "1702345800000-xyz789a",\n      "role": "user",\n      "parts": [{ "type": "text", "text": "How do I reset my password?", "status": "done" }],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:00.000Z"\n    },\n    {\n      "id": "1702345805000-def456b",\n      "role": "assistant",\n      "parts": [\n        { "type": "text", "text": "I can help you reset your password...", "status": "done" }\n      ],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:05.000Z"\n    }\n  ],\n  "createdAt": "2024-01-15T10:30:00Z",\n  "updatedAt": "2024-01-15T10:30:05Z"\n}\n```\n\n### Response (Expired Session)\n\nWhen the session has expired, the response indicates the expiration status:\n\n```json\n{\n  "status": "expired",\n  "sessionId": "cm5xyz123abc456def",\n  "agentId": "cm5xvz7k80001abcd",\n  "createdAt": "2024-01-15T10:30:00Z"\n}\n```\n\nUse the [Restore Session](#restore-session) endpoint to restore an expired session from stored messages.\n\n````\n\n### UIMessage Parts\n\nMessages contain typed `parts` that preserve content ordering:\n\n| Part Type | Description |\n|-----------|-------------|\n| `text` | Text content with `text` and `status` fields |\n| `reasoning` | Extended reasoning with `text` and `status` fields |\n| `tool-call` | Tool execution with `toolCallId`, `toolName`, `displayName`, `args`, `result`, `status` |\n| `operation` | Internal operations with `operationId`, `name`, `operationType`, `status` |\n| `file` | File attachment with `id`, `mediaType`, `url`, `filename`, `size` |\n| `source` | Source reference with `sourceType`, `id`, `url`, `title` |\n| `object` | Structured output with `id`, `typeName`, `object`, `status` |\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agent-sessions/:sessionId \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n````\n\n## Restore Session\n\nRestore an expired session from stored messages. This allows you to continue a conversation after the server-side state has expired.\n\n```\nPOST /api/agent-sessions/:sessionId/restore\n```\n\n### Request Body\n\n```json\n{\n  "messages": [\n    {\n      "id": "1702345800000-xyz789a",\n      "role": "user",\n      "parts": [{ "type": "text", "text": "How do I reset my password?", "status": "done" }],\n      "status": "done",\n      "createdAt": "2024-01-15T10:30:00.000Z"\n    }\n  ],\n  "input": {\n    "COMPANY_NAME": "Acme Corp"\n  }\n}\n```\n\n| Field      | Type        | Required | Description                                                    |\n| ---------- | ----------- | -------- | -------------------------------------------------------------- |\n| `messages` | UIMessage[] | Yes      | Previously stored chat history                                 |\n| `input`    | object      | No       | Session input for system prompt interpolation (same as create) |\n\n### Response\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def",\n  "restored": true\n}\n```\n\n| Field       | Type    | Description                                                             |\n| ----------- | ------- | ----------------------------------------------------------------------- |\n| `sessionId` | string  | The session ID                                                          |\n| `restored`  | boolean | `true` if restored from messages, `false` if session was already active |\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agent-sessions/:sessionId/restore \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "messages": [...],\n    "input": { "COMPANY_NAME": "Acme Corp" }\n  }\'\n```\n\n> **Note**: Store the `UIMessage[]` array after each interaction to enable restoration. The restore endpoint reconstructs the conversation state from these messages.\n\n## Trigger Session\n\nExecute a trigger on a session. Returns a Server-Sent Events stream.\n\n```\nPOST /api/agent-sessions/:sessionId/trigger\n```\n\n### Request Body\n\n```json\n{\n  "triggerName": "user-message",\n  "input": {\n    "USER_MESSAGE": "How do I reset my password?"\n  },\n  "toolResults": []\n}\n```\n\n| Field         | Type   | Required | Description                                    |\n| ------------- | ------ | -------- | ---------------------------------------------- |\n| `triggerName` | string | Yes      | Name of the trigger to execute                 |\n| `input`       | object | No       | Input variables for the trigger                |\n| `toolResults` | array  | No       | Tool results for continuation (handled by SDK) |\n\n### Response\n\nReturns `text/event-stream` with SSE events:\n\n```\ndata: {"type":"start","messageId":"msg-123"}\n\ndata: {"type":"block-start","blockId":"b1","blockName":"Add user message","blockType":"add-message","display":"hidden"}\n\ndata: {"type":"block-end","blockId":"b1"}\n\ndata: {"type":"block-start","blockId":"b2","blockName":"Respond to user","blockType":"next-message","display":"stream","outputToChat":true}\n\ndata: {"type":"text-start","id":"t1"}\n\ndata: {"type":"text-delta","id":"t1","delta":"I"}\n\ndata: {"type":"text-delta","id":"t1","delta":" can"}\n\ndata: {"type":"text-delta","id":"t1","delta":" help"}\n\ndata: {"type":"text-delta","id":"t1","delta":" you"}\n\ndata: {"type":"text-delta","id":"t1","delta":" reset"}\n\ndata: {"type":"text-delta","id":"t1","delta":" your"}\n\ndata: {"type":"text-delta","id":"t1","delta":" password"}\n\ndata: {"type":"text-delta","id":"t1","delta":"!"}\n\ndata: {"type":"text-end","id":"t1"}\n\ndata: {"type":"block-end","blockId":"b2"}\n\ndata: {"type":"finish","finishReason":"stop"}\n\ndata: [DONE]\n```\n\n### Event Types\n\n| Event                   | Description                        |\n| ----------------------- | ---------------------------------- |\n| `start`                 | Stream started                     |\n| `finish`                | Execution complete                 |\n| `error`                 | Error occurred                     |\n| `block-start`           | Execution block started            |\n| `block-end`             | Execution block completed          |\n| `text-start`            | Text generation started            |\n| `text-delta`            | Incremental text content           |\n| `text-end`              | Text generation ended              |\n| `reasoning-start`       | Extended reasoning started         |\n| `reasoning-delta`       | Reasoning content                  |\n| `reasoning-end`         | Extended reasoning ended           |\n| `tool-input-start`      | Tool call initiated                |\n| `tool-input-delta`      | Tool arguments streaming           |\n| `tool-input-end`        | Tool arguments streaming ended     |\n| `tool-input-available`  | Tool input complete                |\n| `tool-output-available` | Tool completed with result         |\n| `tool-output-error`     | Tool failed                        |\n| `tool-request`          | Platform requesting tool execution |\n| `file-available`        | File ready for display/download    |\n| `resource-update`       | Resource value changed             |\n\n### Example\n\n```bash\ncurl -N -X POST https://octavus.ai/api/agent-sessions/:sessionId/trigger \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "triggerName": "user-message",\n    "input": { "USER_MESSAGE": "How do I reset my password?" }\n  }\'\n```\n\n## Tool Continuation\n\nWhen the agent calls external tools, you\'ll receive a `tool-request` event. Execute the tools and send results back:\n\n```json\n{\n  "triggerName": "user-message",\n  "input": { "USER_MESSAGE": "..." },\n  "toolResults": [\n    {\n      "toolCallId": "tc_123",\n      "toolName": "get-user-account",\n      "result": {\n        "name": "Demo User",\n        "email": "demo@example.com"\n      }\n    }\n  ]\n}\n```\n\nThe Server SDK handles this continuation pattern automatically.\n\n## Upload URLs\n\nGet presigned URLs for file uploads. Files are uploaded directly to S3.\n\n```\nPOST /api/files/upload-urls\n```\n\n### Request Body\n\n```json\n{\n  "sessionId": "cm5xyz123abc456def",\n  "files": [\n    {\n      "filename": "photo.jpg",\n      "mediaType": "image/jpeg",\n      "size": 102400\n    }\n  ]\n}\n```\n\n| Field               | Type   | Required | Description                         |\n| ------------------- | ------ | -------- | ----------------------------------- |\n| `sessionId`         | string | Yes      | Session ID to associate files with  |\n| `files`             | array  | Yes      | Array of file metadata (1-20 files) |\n| `files[].filename`  | string | Yes      | Original filename                   |\n| `files[].mediaType` | string | Yes      | MIME type (e.g., `image/png`)       |\n| `files[].size`      | number | Yes      | File size in bytes                  |\n\n### Response\n\n```json\n{\n  "files": [\n    {\n      "id": "file-abc123",\n      "uploadUrl": "https://s3.amazonaws.com/bucket/key?...",\n      "downloadUrl": "https://s3.amazonaws.com/bucket/key?..."\n    }\n  ]\n}\n```\n\n### Upload Flow\n\n1. Request upload URLs from the platform\n2. PUT file content to `uploadUrl` with `Content-Type` header\n3. Use `downloadUrl` as the `url` in `FileReference`\n4. Include `FileReference` in trigger input\n\n### Supported Types\n\n| Category  | Media Types                                                          |\n| --------- | -------------------------------------------------------------------- |\n| Images    | `image/jpeg`, `image/png`, `image/gif`, `image/webp`                 |\n| Documents | `application/pdf`, `text/plain`, `text/markdown`, `application/json` |\n\n### Limits\n\n| Limit                 | Value      |\n| --------------------- | ---------- |\n| Max file size         | 10 MB      |\n| Max total per request | 50 MB      |\n| Max files per request | 20         |\n| Upload URL expiry     | 15 minutes |\n| Download URL expiry   | 24 hours   |\n',
+        excerpt: "Sessions API Sessions represent conversations with agents. They store conversation history, resources, and variables. All session endpoints require an API key with the Sessions permission.  Create...",
         order: 2
       },
       {
@@ -587,8 +587,8 @@ var sections_default = [
         section: "api-reference",
         title: "Agents",
         description: "Agent management API endpoints.",
-        content: '\n# Agents API\n\nManage agent definitions including protocols and prompts.\n\n## List Agents\n\nGet all agents in the project.\n\n```\nGET /api/agents\n```\n\n### Response\n\n```json\n{\n  "agents": [\n    {\n      "id": "cm5xvz7k80001abcd",\n      "slug": "support-chat",\n      "name": "Support Chat",\n      "description": "Customer support agent",\n      "format": "interactive",\n      "createdAt": "2024-01-10T08:00:00Z",\n      "updatedAt": "2024-01-15T10:00:00Z"\n    }\n  ]\n}\n```\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agents \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n## Get Agent\n\nGet a single agent by ID.\n\n```\nGET /api/agents/:id\n```\n\n### Response\n\n```json\n{\n  "id": "cm5xvz7k80001abcd",\n  "settings": {\n    "slug": "support-chat",\n    "name": "Support Chat",\n    "description": "Customer support agent",\n    "format": "interactive"\n  },\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "You are a support agent for {{COMPANY_NAME}}..."\n    },\n    {\n      "name": "user-message",\n      "content": "{{USER_MESSAGE}}"\n    }\n  ]\n}\n```\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agents/:agentId \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n> **Tip:** You can also view and edit agents directly in the [platform](https://octavus.ai), or use the [CLI](/docs/server-sdk/cli) (`octavus list`) for local workflows.\n\n## Create Agent\n\nCreate a new agent.\n\n```\nPOST /api/agents\n```\n\n### Request Body\n\n```json\n{\n  "settings": {\n    "slug": "support-chat",\n    "name": "Support Chat",\n    "description": "Customer support agent",\n    "format": "interactive"\n  },\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "You are a support agent..."\n    }\n  ]\n}\n```\n\n| Field                  | Type   | Required | Description               |\n| ---------------------- | ------ | -------- | ------------------------- |\n| `settings.slug`        | string | Yes      | URL-safe identifier       |\n| `settings.name`        | string | Yes      | Display name              |\n| `settings.description` | string | No       | Agent description         |\n| `settings.format`      | string | Yes      | `interactive` or `worker` |\n| `protocol`             | string | Yes      | YAML protocol definition  |\n| `prompts`              | array  | Yes      | Prompt files              |\n\n### Response\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "message": "Agent created successfully"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agents \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "settings": {\n      "slug": "my-agent",\n      "name": "My Agent",\n      "format": "interactive"\n    },\n    "protocol": "agent:\\n  model: anthropic/claude-sonnet-4-5\\n  system: system",\n    "prompts": [\n      { "name": "system", "content": "You are a helpful assistant." }\n    ]\n  }\'\n```\n\n## Update Agent\n\nUpdate an existing agent.\n\n```\nPATCH /api/agents/:id\n```\n\n### Request Body\n\n```json\n{\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "Updated system prompt..."\n    }\n  ]\n}\n```\n\nAll fields are optional. Only provided fields are updated.\n\n### Response\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "message": "Agent updated successfully"\n}\n```\n\n### Example\n\n```bash\ncurl -X PATCH https://octavus.ai/api/agents/:agentId \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "protocol": "agent:\\n  model: anthropic/claude-sonnet-4-5\\n  system: system\\n  thinking: high"\n  }\'\n```\n\n## Creating and Managing Agents\n\nThere are two ways to manage agents:\n\n### Platform UI\n\nCreate and edit agents directly at [octavus.ai](https://octavus.ai). The web editor provides real-time validation and is the easiest way to get started. Copy the agent ID from the URL to use in your application.\n\n### CLI (Local Development)\n\nFor version-controlled agent definitions, use the [Octavus CLI](/docs/server-sdk/cli):\n\n```bash\noctavus sync ./agents/support-chat\n```\n\nThis creates the agent if it doesn\'t exist, or updates it if it does. The CLI outputs the agent ID which you should store in an environment variable.\n\nFor CI/CD integration, see the [CLI documentation](/docs/server-sdk/cli#cicd-integration).\n',
-        excerpt: "Agents API Manage agent definitions including protocols and prompts.  List Agents Get all agents in the project.  Response  Example  Get Agent Get a single agent by ID.  Response  Example > Tip: You...",
+        content: '\n# Agents API\n\nManage agent definitions including protocols and prompts.\n\n## Permissions\n\n| Endpoint               | Method | Permission Required |\n| ---------------------- | ------ | ------------------- |\n| `/api/agents`          | GET    | Agents OR Sessions  |\n| `/api/agents/:id`      | GET    | Agents OR Sessions  |\n| `/api/agents`          | POST   | Agents              |\n| `/api/agents/:id`      | PATCH  | Agents              |\n| `/api/agents/validate` | POST   | Agents              |\n\nRead endpoints work with either permission since both the CLI (for sync) and Server SDK (for sessions) need to read agent definitions.\n\n## List Agents\n\nGet all agents in the project.\n\n```\nGET /api/agents\n```\n\n### Response\n\n```json\n{\n  "agents": [\n    {\n      "id": "cm5xvz7k80001abcd",\n      "slug": "support-chat",\n      "name": "Support Chat",\n      "description": "Customer support agent",\n      "format": "interactive",\n      "createdAt": "2024-01-10T08:00:00Z",\n      "updatedAt": "2024-01-15T10:00:00Z"\n    }\n  ]\n}\n```\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agents \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n## Get Agent\n\nGet a single agent by ID.\n\n```\nGET /api/agents/:id\n```\n\n### Response\n\n```json\n{\n  "id": "cm5xvz7k80001abcd",\n  "settings": {\n    "slug": "support-chat",\n    "name": "Support Chat",\n    "description": "Customer support agent",\n    "format": "interactive"\n  },\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "You are a support agent for {{COMPANY_NAME}}..."\n    },\n    {\n      "name": "user-message",\n      "content": "{{USER_MESSAGE}}"\n    }\n  ]\n}\n```\n\n### Example\n\n```bash\ncurl https://octavus.ai/api/agents/:agentId \\\n  -H "Authorization: Bearer YOUR_API_KEY"\n```\n\n> **Tip:** You can also view and edit agents directly in the [platform](https://octavus.ai), or use the [CLI](/docs/server-sdk/cli) (`octavus list`) for local workflows.\n\n## Create Agent\n\nCreate a new agent.\n\n```\nPOST /api/agents\n```\n\n### Request Body\n\n```json\n{\n  "settings": {\n    "slug": "support-chat",\n    "name": "Support Chat",\n    "description": "Customer support agent",\n    "format": "interactive"\n  },\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "You are a support agent..."\n    }\n  ]\n}\n```\n\n| Field                  | Type   | Required | Description               |\n| ---------------------- | ------ | -------- | ------------------------- |\n| `settings.slug`        | string | Yes      | URL-safe identifier       |\n| `settings.name`        | string | Yes      | Display name              |\n| `settings.description` | string | No       | Agent description         |\n| `settings.format`      | string | Yes      | `interactive` or `worker` |\n| `protocol`             | string | Yes      | YAML protocol definition  |\n| `prompts`              | array  | Yes      | Prompt files              |\n\n### Response\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "message": "Agent created successfully"\n}\n```\n\n### Example\n\n```bash\ncurl -X POST https://octavus.ai/api/agents \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "settings": {\n      "slug": "my-agent",\n      "name": "My Agent",\n      "format": "interactive"\n    },\n    "protocol": "agent:\\n  model: anthropic/claude-sonnet-4-5\\n  system: system",\n    "prompts": [\n      { "name": "system", "content": "You are a helpful assistant." }\n    ]\n  }\'\n```\n\n## Update Agent\n\nUpdate an existing agent.\n\n```\nPATCH /api/agents/:id\n```\n\n### Request Body\n\n```json\n{\n  "protocol": "input:\\n  COMPANY_NAME: { type: string }\\n...",\n  "prompts": [\n    {\n      "name": "system",\n      "content": "Updated system prompt..."\n    }\n  ]\n}\n```\n\nAll fields are optional. Only provided fields are updated.\n\n### Response\n\n```json\n{\n  "agentId": "cm5xvz7k80001abcd",\n  "message": "Agent updated successfully"\n}\n```\n\n### Example\n\n```bash\ncurl -X PATCH https://octavus.ai/api/agents/:agentId \\\n  -H "Authorization: Bearer YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "protocol": "agent:\\n  model: anthropic/claude-sonnet-4-5\\n  system: system\\n  thinking: high"\n  }\'\n```\n\n## Creating and Managing Agents\n\nThere are two ways to manage agents:\n\n### Platform UI\n\nCreate and edit agents directly at [octavus.ai](https://octavus.ai). The web editor provides real-time validation and is the easiest way to get started. Copy the agent ID from the URL to use in your application.\n\n### CLI (Local Development)\n\nFor version-controlled agent definitions, use the [Octavus CLI](/docs/server-sdk/cli):\n\n```bash\noctavus sync ./agents/support-chat\n```\n\nThis creates the agent if it doesn\'t exist, or updates it if it does. The CLI outputs the agent ID which you should store in an environment variable.\n\nFor CI/CD integration, see the [CLI documentation](/docs/server-sdk/cli#cicd-integration).\n',
+        excerpt: "Agents API Manage agent definitions including protocols and prompts.  Permissions | Endpoint               | Method | Permission Required | | ---------------------- | ------ | ------------------- | |...",
         order: 3
       }
     ]
@@ -660,4 +660,4 @@ export {
   getDocSlugs,
   getSectionBySlug
 };
-//# sourceMappingURL=chunk-WJ2W3DUC.js.map
+//# sourceMappingURL=chunk-HFF2TVGV.js.map