@octavus/docs 0.0.1

package/content/05-api-reference/01-overview.md

@@ -0,0 +1,129 @@
+---
+title: Overview
+description: REST API overview and authentication.
+---
+
+# API Reference
+
+The Octavus API is a RESTful API that enables programmatic access to agent management and session execution.
+
+## Base URL
+
+```
+https://octavus.ai
+```
+
+## Authentication
+
+All API requests require authentication using a Bearer token:
+
+```bash
+curl -H "Authorization: Bearer YOUR_API_KEY" \
+  https://octavus.ai/api/agents
+```
+
+API keys can be created in the Octavus Platform under Project Settings → API Keys.
+
+## Response Format
+
+All responses are JSON. Success responses return the data directly (not wrapped in a `data` field).
+
+### Success Response
+
+```json
+{
+  "sessionId": "sess_abc123"
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Agent not found"
+  }
+}
+```
+
+## HTTP Status Codes
+
+| Code | Description |
+|------|-------------|
+| 200 | Success |
+| 201 | Created |
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid API key |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found |
+| 429 | Too Many Requests - Rate limited |
+| 500 | Internal Server Error |
+
+## Rate Limits
+
+- **Standard tier**: 100 requests/minute
+- **Pro tier**: 1,000 requests/minute
+- **Enterprise**: Custom limits
+
+Rate limit headers are included in responses:
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1735312800
+```
+
+## Endpoints Overview
+
+### Agents
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/agents` | List all agents |
+| GET | `/api/agents/:id` | Get agent by ID |
+| POST | `/api/agents` | Create agent |
+| PATCH | `/api/agents/:id` | Update agent |
+
+### Sessions
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/agent-sessions` | Create session |
+| GET | `/api/agent-sessions/:id` | Get session state |
+| POST | `/api/agent-sessions/:id/trigger` | Execute trigger (SSE) |
+
+## Streaming
+
+The trigger endpoint returns Server-Sent Events (SSE):
+
+```bash
+curl -N -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"triggerName": "user-message", "input": {"USER_MESSAGE": "Hello"}}' \
+  https://octavus.ai/api/agent-sessions/SESSION_ID/trigger
+```
+
+Response format:
+
+```
+data: {"type":"block-start","blockId":"...","blockName":"Respond"}
+
+data: {"type":"text-delta","content":"Hello"}
+
+data: {"type":"text-delta","content":"!"}
+
+data: {"type":"done","finishReason":"stop"}
+
+data: [DONE]
+```
+
+## SDKs
+
+We recommend using our SDKs instead of calling the API directly:
+
+- **Server SDK**: `@octavus/server-sdk` - For Node.js backends
+- **Client SDK**: `@octavus/client-sdk` - For React frontends
+
+The SDKs handle authentication, streaming, and tool execution automatically.
+

package/content/05-api-reference/02-sessions.md

@@ -0,0 +1,232 @@
+---
+title: Sessions
+description: Session management API endpoints.
+---
+
+# Sessions API
+
+Sessions represent conversations with agents. They store conversation history, resources, and variables.
+
+## Create Session
+
+Create a new agent session.
+
+```
+POST /api/agent-sessions
+```
+
+### Request Body
+
+```json
+{
+  "agentId": "support-chat",
+  "input": {
+    "COMPANY_NAME": "Acme Corp",
+    "PRODUCT_NAME": "Widget Pro",
+    "USER_ID": "user-123"
+  }
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `agentId` | string | Yes | Agent identifier (slug) |
+| `input` | object | No | Input variables for the agent |
+
+### Response
+
+```json
+{
+  "sessionId": "sess_abc123xyz"
+}
+```
+
+### Example
+
+```bash
+curl -X POST https://octavus.ai/api/agent-sessions \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agentId": "support-chat",
+    "input": {
+      "COMPANY_NAME": "Acme Corp",
+      "PRODUCT_NAME": "Widget Pro"
+    }
+  }'
+```
+
+## Get Session
+
+Retrieve session state including messages and resources.
+
+```
+GET /api/agent-sessions/:sessionId
+```
+
+### Response
+
+```json
+{
+  "id": "sess_abc123xyz",
+  "agentId": "support-chat",
+  "input": {
+    "COMPANY_NAME": "Acme Corp",
+    "PRODUCT_NAME": "Widget Pro"
+  },
+  "variables": {},
+  "resources": {
+    "CONVERSATION_SUMMARY": ""
+  },
+  "messages": [
+    {
+      "id": "msg_1",
+      "role": "user",
+      "parts": [
+        { "type": "text", "visible": true, "content": "How do I reset my password?" }
+      ],
+      "content": "How do I reset my password?",
+      "createdAt": "2024-01-15T10:30:00Z"
+    },
+    {
+      "id": "msg_2",
+      "role": "assistant",
+      "parts": [
+        { "type": "text", "visible": true, "content": "I can help you reset your password..." }
+      ],
+      "content": "I can help you reset your password...",
+      "createdAt": "2024-01-15T10:30:05Z"
+    }
+  ],
+  "createdAt": "2024-01-15T10:30:00Z",
+  "updatedAt": "2024-01-15T10:30:05Z"
+}
+```
+
+### Example
+
+```bash
+curl https://octavus.ai/api/agent-sessions/sess_abc123xyz \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+## Trigger Session
+
+Execute a trigger on a session. Returns a Server-Sent Events stream.
+
+```
+POST /api/agent-sessions/:sessionId/trigger
+```
+
+### Request Body
+
+```json
+{
+  "triggerName": "user-message",
+  "input": {
+    "USER_MESSAGE": "How do I reset my password?"
+  },
+  "toolResults": []
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `triggerName` | string | Yes | Name of the trigger to execute |
+| `input` | object | No | Input variables for the trigger |
+| `toolResults` | array | No | Tool results for continuation (handled by SDK) |
+
+### Response
+
+Returns `text/event-stream` with SSE events:
+
+```
+data: {"type":"block-start","blockId":"b1","blockName":"Add user message","blockType":"add-message","display":"hidden"}
+
+data: {"type":"block-end","blockId":"b1"}
+
+data: {"type":"block-start","blockId":"b2","blockName":"Respond to user","blockType":"next-message","display":"stream","outputToChat":true}
+
+data: {"type":"text-start","id":"t1"}
+
+data: {"type":"text-delta","content":"I"}
+
+data: {"type":"text-delta","content":" can"}
+
+data: {"type":"text-delta","content":" help"}
+
+data: {"type":"text-delta","content":" you"}
+
+data: {"type":"text-delta","content":" reset"}
+
+data: {"type":"text-delta","content":" your"}
+
+data: {"type":"text-delta","content":" password"}
+
+data: {"type":"text-delta","content":"!"}
+
+data: {"type":"text-end","id":"t1"}
+
+data: {"type":"block-end","blockId":"b2"}
+
+data: {"type":"done","finishReason":"stop"}
+
+data: [DONE]
+```
+
+### Event Types
+
+| Event | Description |
+|-------|-------------|
+| `block-start` | Execution block started |
+| `block-end` | Execution block completed |
+| `text-start` | Text generation started |
+| `text-delta` | Incremental text content |
+| `text-end` | Text generation ended |
+| `tool-call-start` | Tool call initiated |
+| `tool-call-args` | Tool arguments (JSON string) |
+| `tool-call-result` | Tool completed with result |
+| `tool-call-error` | Tool failed |
+| `tool-request` | Platform requesting tool execution |
+| `thinking-start` | Extended reasoning started |
+| `thinking-delta` | Reasoning content |
+| `thinking-end` | Extended reasoning ended |
+| `resource-update` | Resource value changed |
+| `done` | Execution complete |
+| `error` | Error occurred |
+
+### Example
+
+```bash
+curl -N -X POST https://octavus.ai/api/agent-sessions/sess_abc123xyz/trigger \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "triggerName": "user-message",
+    "input": { "USER_MESSAGE": "How do I reset my password?" }
+  }'
+```
+
+## Tool Continuation
+
+When the agent calls external tools, you'll receive a `tool-request` event. Execute the tools and send results back:
+
+```json
+{
+  "triggerName": "user-message",
+  "input": { "USER_MESSAGE": "..." },
+  "toolResults": [
+    {
+      "toolCallId": "tc_123",
+      "toolName": "get-user-account",
+      "result": {
+        "name": "Demo User",
+        "email": "demo@example.com"
+      }
+    }
+  ]
+}
+```
+
+The Server SDK handles this continuation pattern automatically.
+

package/content/05-api-reference/03-agents.md

@@ -0,0 +1,222 @@
+---
+title: Agents
+description: Agent management API endpoints.
+---
+
+# Agents API
+
+Manage agent definitions including protocols and prompts.
+
+## List Agents
+
+Get all agents in the project.
+
+```
+GET /api/agents
+```
+
+### Response
+
+```json
+{
+  "agents": [
+    {
+      "id": "agt_abc123",
+      "slug": "support-chat",
+      "name": "Support Chat",
+      "description": "Customer support agent",
+      "format": "interactive",
+      "createdAt": "2024-01-10T08:00:00Z",
+      "updatedAt": "2024-01-15T10:00:00Z"
+    }
+  ]
+}
+```
+
+### Example
+
+```bash
+curl https://octavus.ai/api/agents \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+## Get Agent
+
+Get a single agent by ID or slug.
+
+```
+GET /api/agents/:id
+GET /api/agents/:slug?by=slug
+```
+
+### Response
+
+```json
+{
+  "id": "agt_abc123",
+  "slug": "support-chat",
+  "name": "Support Chat",
+  "description": "Customer support agent",
+  "format": "interactive",
+  "protocol": "input:\n  COMPANY_NAME: { type: string }\n...",
+  "prompts": [
+    {
+      "name": "system",
+      "content": "You are a support agent for {{COMPANY_NAME}}..."
+    },
+    {
+      "name": "user-message",
+      "content": "{{USER_MESSAGE}}"
+    }
+  ],
+  "createdAt": "2024-01-10T08:00:00Z",
+  "updatedAt": "2024-01-15T10:00:00Z"
+}
+```
+
+### Example
+
+```bash
+# By ID
+curl https://octavus.ai/api/agents/agt_abc123 \
+  -H "Authorization: Bearer YOUR_API_KEY"
+
+# By slug
+curl "https://octavus.ai/api/agents/support-chat?by=slug" \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+## Create Agent
+
+Create a new agent.
+
+```
+POST /api/agents
+```
+
+### Request Body
+
+```json
+{
+  "settings": {
+    "slug": "support-chat",
+    "name": "Support Chat",
+    "description": "Customer support agent",
+    "format": "interactive"
+  },
+  "protocol": "input:\n  COMPANY_NAME: { type: string }\n...",
+  "prompts": [
+    {
+      "name": "system",
+      "content": "You are a support agent..."
+    }
+  ]
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `settings.slug` | string | Yes | URL-safe identifier |
+| `settings.name` | string | Yes | Display name |
+| `settings.description` | string | No | Agent description |
+| `settings.format` | string | Yes | `interactive` or `generation` |
+| `protocol` | string | Yes | YAML protocol definition |
+| `prompts` | array | Yes | Prompt files |
+
+### Response
+
+```json
+{
+  "agentId": "agt_abc123"
+}
+```
+
+### Example
+
+```bash
+curl -X POST https://octavus.ai/api/agents \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "settings": {
+      "slug": "my-agent",
+      "name": "My Agent",
+      "format": "interactive"
+    },
+    "protocol": "agent:\n  model: anthropic/claude-sonnet-4-5\n  system: system",
+    "prompts": [
+      { "name": "system", "content": "You are a helpful assistant." }
+    ]
+  }'
+```
+
+## Update Agent
+
+Update an existing agent.
+
+```
+PATCH /api/agents/:id
+PATCH /api/agents/:slug?by=slug
+```
+
+### Request Body
+
+```json
+{
+  "protocol": "input:\n  COMPANY_NAME: { type: string }\n...",
+  "prompts": [
+    {
+      "name": "system",
+      "content": "Updated system prompt..."
+    }
+  ]
+}
+```
+
+All fields are optional. Only provided fields are updated.
+
+### Response
+
+```json
+{
+  "agentId": "agt_abc123"
+}
+```
+
+### Example
+
+```bash
+curl -X PATCH https://octavus.ai/api/agents/agt_abc123 \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "protocol": "agent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  thinking: high"
+  }'
+```
+
+## Sync Agent
+
+The Server SDK provides a `sync` method that creates or updates an agent:
+
+```typescript
+const { agentId, created } = await client.agents.sync({
+  settings: {
+    slug: 'support-chat',
+    name: 'Support Chat',
+    format: 'interactive',
+  },
+  protocol: protocolYaml,
+  prompts: [
+    { name: 'system', content: systemPrompt },
+  ],
+});
+
+if (created) {
+  console.log('Created new agent:', agentId);
+} else {
+  console.log('Updated existing agent:', agentId);
+}
+```
+
+This is useful for CI/CD pipelines to deploy agent updates.
+

package/content/05-api-reference/_meta.md

@@ -0,0 +1,4 @@
+---
+title: API Reference
+description: REST API reference for the Octavus platform.
+---