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 Session

Create a new agent session.

text

POST /api/agent-sessions

Request Body

json

{
  "agentId": "cm5xvz7k80001abcd",
  "input": {
    "COMPANY_NAME": "Acme Corp",
    "PRODUCT_NAME": "Widget Pro",
    "USER_ID": "user-123"
  }
}

Field	Type	Required	Description
`agentId`	string	Yes	Agent ID (the `id` field, not `slug`)
`input`	object	No	Input variables for the agent

Getting the agent ID: Copy the ID from the agent URL in the platform (e.g., octavus.ai/projects/.../agents/clxyz123), or use the CLI (octavus sync ./agents/my-agent) for local development workflows.

Response

json

{
  "sessionId": "cm5xyz123abc456def"
}

Example

bash

curl -X POST https://octavus.ai/api/agent-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "cm5xvz7k80001abcd",
    "input": {
      "COMPANY_NAME": "Acme Corp",
      "PRODUCT_NAME": "Widget Pro"
    }
  }'

Get Session

Retrieve session state. Returns UI-ready messages for active sessions, or expiration info for expired sessions.

text

GET /api/agent-sessions/:sessionId

Note: For an agent configured with context management (maxToolOutputTokens and/or contextManagement), the returned session state is the agent's bounded working memory, not a byte-complete transcript: tool results are the bounded previews and, once the session has compacted, older turns are represented by the running summary. For the complete, untruncated history - every tool result at full size - read the session's execution logs / trace, which is the durable record.

Query Parameters

Parameter	Type	Description
`format`	string	Optional. Use `format=ui` for UI-ready messages only

Response (Active Session)

When the session is active, the response includes UIMessage objects:

json

{
  "id": "cm5xyz123abc456def",
  "agentId": "cm5xvz7k80001abcd",
  "status": "active",
  "input": {
    "COMPANY_NAME": "Acme Corp",
    "PRODUCT_NAME": "Widget Pro"
  },
  "variables": {},
  "resources": {
    "CONVERSATION_SUMMARY": ""
  },
  "messages": [
    {
      "id": "1702345800000-xyz789a",
      "role": "user",
      "parts": [{ "type": "text", "text": "How do I reset my password?", "status": "done" }],
      "status": "done",
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "1702345805000-def456b",
      "role": "assistant",
      "parts": [
        { "type": "text", "text": "I can help you reset your password...", "status": "done" }
      ],
      "status": "done",
      "createdAt": "2024-01-15T10:30:05.000Z"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:05Z"
}

Response (Expired Session)

When the session has expired, the response indicates the expiration status:

json

{
  "status": "expired",
  "sessionId": "cm5xyz123abc456def",
  "agentId": "cm5xvz7k80001abcd",
  "createdAt": "2024-01-15T10:30:00Z"
}

Use the Restore Session endpoint to restore an expired session from stored messages.

text


### UIMessage Parts

Messages contain typed `parts` that preserve content ordering:

| Part Type | Description |
|-----------|-------------|
| `text` | Text content with `text` and `status` fields |
| `reasoning` | Extended reasoning with `text` and `status` fields |
| `tool-call` | Tool execution with `toolCallId`, `toolName`, `displayName`, `args`, `result`, `status` |
| `operation` | Internal operations with `operationId`, `name`, `operationType`, `status` |
| `file` | File attachment with `id`, `mediaType`, `url`, `filename`, `size` |
| `source` | Source reference with `sourceType`, `id`, `url`, `title` |
| `object` | Structured output with `id`, `typeName`, `object`, `status` |

### Example

```bash
curl https://octavus.ai/api/agent-sessions/:sessionId \
  -H "Authorization: Bearer YOUR_API_KEY"

Restore Session

Restore an expired session from stored messages. This allows you to continue a conversation after the server-side state has expired.

text

POST /api/agent-sessions/:sessionId/restore

Request Body

json

{
  "messages": [
    {
      "id": "1702345800000-xyz789a",
      "role": "user",
      "parts": [{ "type": "text", "text": "How do I reset my password?", "status": "done" }],
      "status": "done",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "input": {
    "COMPANY_NAME": "Acme Corp"
  }
}

Field	Type	Required	Description
`messages`	UIMessage[]	Yes	Previously stored chat history
`input`	object	No	Session input for system prompt interpolation (same as create)

Response

json

{
  "sessionId": "cm5xyz123abc456def",
  "restored": true
}

Field	Type	Description
`sessionId`	string	The session ID
`restored`	boolean	`true` if restored from messages, `false` if session was already active

Example

bash

curl -X POST https://octavus.ai/api/agent-sessions/:sessionId/restore \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [...],
    "input": { "COMPANY_NAME": "Acme Corp" }
  }'

Note: Store the UIMessage[] array after each interaction to enable restoration. The restore endpoint reconstructs the conversation state from these messages.

Clear Session

Clear session state, transitioning it to expired status. The session can be restored afterwards with the Restore Session endpoint.

This is idempotent - clearing an already expired session succeeds without error.

text

DELETE /api/agent-sessions/:sessionId

Response

json

{
  "sessionId": "cm5xyz123abc456def",
  "cleared": true
}

Example

bash

curl -X DELETE https://octavus.ai/api/agent-sessions/:sessionId \
  -H "Authorization: Bearer YOUR_API_KEY"

Trigger Session

Execute a trigger on a session. Returns a Server-Sent Events stream.

text

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)
`rollbackAfterMessageId`	string \| null	No	For retry: ID of the last message to keep. Messages after this are removed. `null` = truncate all.

Response

Returns text/event-stream with SSE events:

text

data: {"type":"start","messageId":"msg-123"}

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","id":"t1","delta":"I"}

data: {"type":"text-delta","id":"t1","delta":" can"}

data: {"type":"text-delta","id":"t1","delta":" help"}

data: {"type":"text-delta","id":"t1","delta":" you"}

data: {"type":"text-delta","id":"t1","delta":" reset"}

data: {"type":"text-delta","id":"t1","delta":" your"}

data: {"type":"text-delta","id":"t1","delta":" password"}

data: {"type":"text-delta","id":"t1","delta":"!"}

data: {"type":"text-end","id":"t1"}

data: {"type":"block-end","blockId":"b2"}

data: {"type":"finish","finishReason":"stop"}

data: [DONE]

Event Types

Event	Description
`start`	Stream started
`finish`	Execution complete
`error`	Error occurred
`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
`reasoning-start`	Extended reasoning started
`reasoning-delta`	Reasoning content
`reasoning-end`	Extended reasoning ended
`tool-input-start`	Tool call initiated
`tool-input-delta`	Tool arguments streaming
`tool-input-end`	Tool arguments streaming ended
`tool-input-available`	Tool input complete
`tool-output-available`	Tool completed with result
`tool-output-error`	Tool failed
`tool-request`	Platform requesting tool execution
`file-available`	File ready for display/download
`resource-update`	Resource value changed

Example

bash

curl -N -X POST https://octavus.ai/api/agent-sessions/:sessionId/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.

Upload URLs

Get presigned URLs for file uploads. Files are uploaded directly to S3.

text

POST /api/files/upload-urls

Request Body

json

{
  "sessionId": "cm5xyz123abc456def",
  "files": [
    {
      "filename": "photo.jpg",
      "mediaType": "image/jpeg",
      "size": 102400
    }
  ]
}

Field	Type	Required	Description
`sessionId`	string	Yes	Session ID to associate files with
`files`	array	Yes	Array of file metadata (1-20 files)
`files[].filename`	string	Yes	Original filename
`files[].mediaType`	string	Yes	MIME type (e.g., `image/png`)
`files[].size`	number	Yes	File size in bytes

Response

json

{
  "files": [
    {
      "id": "file-abc123",
      "uploadUrl": "https://s3.amazonaws.com/bucket/key?...",
      "downloadUrl": "https://s3.amazonaws.com/bucket/key?..."
    }
  ]
}

Upload Flow

Request upload URLs from the platform
PUT file content to uploadUrl with Content-Type header
Use downloadUrl as the url in FileReference
Include FileReference in trigger input

Supported Types

Category	Media Types
Images	`image/jpeg`, `image/png`, `image/gif`, `image/webp`
Documents	`application/pdf`, `text/plain`, `text/markdown`, `application/json`

Limits

Limit	Value
Max file size	10 MB
Max total per request	50 MB
Max files per request	20
Upload URL expiry	15 minutes
Download URL expiry	24 hours