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

Request Body

json

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/agents/clxyz123), or use the CLI (octavus sync ./agents/my-agent) for local development workflows.

Response

json

Example

bash

Get Session

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

text

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

Response (Expired Session)

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

json

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

text

Restore Session

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

text

Request Body

json

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

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

Example

bash

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

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:

text

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

Tool Continuation

When the agent calls external tools, you'll receive a tool-request event. Execute the tools and send results back:

json

The Server SDK handles this continuation pattern automatically.

Upload URLs

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

text

Request Body

json

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

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