---
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": "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 |

> To get the agent ID, copy it from the platform URL, use [Get Agent by slug](/docs/api-reference/agents#get-agent) (`GET /api/agents/:slug?by=slug`), or the SDK's `agents.getBySlug()` method.

### 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 including UI-ready messages and resources.

```
GET /api/agent-sessions/:sessionId
```

### Response

The response includes `UIMessage` objects that can be passed directly to the client SDK's `initialMessages` option:

```json
{
  "id": "cm5xyz123abc456def",
  "agentId": "cm5xvz7k80001abcd",
  "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"
}
```

### 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` |

### Example

```bash
curl 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.

```
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":"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 |
| `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.
