> ## Documentation Index
> Fetch the complete documentation index at: https://www.sentrial.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions API

> REST API endpoints for creating and managing agent sessions.

## Base URL

```
https://api.sentrial.com
```

## Create Session

<ParamField body="name" type="string" required>
  Descriptive name for the session.
</ParamField>

<ParamField body="agentName" type="string" required>
  Agent identifier for grouping.
</ParamField>

<ParamField body="userId" type="string" required>
  External user identifier.
</ParamField>

<ParamField body="metadata" type="object">
  Custom key-value data.
</ParamField>

### Request

```bash theme={null}
POST /api/sdk/sessions
```

```json theme={null}
{
  "name": "Customer Support Request",
  "agentName": "support-agent",
  "userId": "user_123",
  "metadata": {
    "ticketId": "TKT-789",
    "channel": "web_chat"
  }
}
```

### Response

```json theme={null}
{
  "id": "sess_abc123def456",
  "name": "Customer Support Request",
  "agentName": "support-agent",
  "userId": "user_123",
  "status": "active",
  "createdAt": "2025-01-12T10:30:00Z"
}
```

### cURL Example

```bash theme={null}
curl -X POST https://api.sentrial.com/api/sdk/sessions \
  -H "Authorization: Bearer sentrial_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Request",
    "agentName": "support-agent",
    "userId": "user_123"
  }'
```

## Update Session

<ParamField body="status" type="string">
  `"completed"` or `"failed"`.
</ParamField>

<ParamField body="success" type="boolean">
  Whether session completed successfully.
</ParamField>

<ParamField body="failureReason" type="string">
  Reason for failure if `success=false`.
</ParamField>

<ParamField body="estimatedCost" type="number">
  Total cost in USD.
</ParamField>

<ParamField body="durationMs" type="number">
  Duration in milliseconds.
</ParamField>

<ParamField body="promptTokens" type="number">
  Input tokens used.
</ParamField>

<ParamField body="completionTokens" type="number">
  Output tokens used.
</ParamField>

<ParamField body="totalTokens" type="number">
  Total tokens.
</ParamField>

<ParamField body="customMetrics" type="object">
  Custom numeric metrics.
</ParamField>

### Request

```bash theme={null}
PATCH /api/sdk/sessions/:id
```

```json theme={null}
{
  "status": "completed",
  "success": true,
  "estimatedCost": 0.045,
  "durationMs": 3500,
  "promptTokens": 1500,
  "completionTokens": 500,
  "totalTokens": 2000,
  "customMetrics": {
    "satisfaction": 4.5,
    "resolution_time": 120
  }
}
```

### Response

```json theme={null}
{
  "id": "sess_abc123def456",
  "name": "Customer Support Request",
  "status": "completed",
  "success": true,
  "estimatedCost": 0.045,
  "durationMs": 3500,
  "completedAt": "2025-01-12T10:30:03Z"
}
```

### cURL Example

```bash theme={null}
curl -X PATCH https://api.sentrial.com/api/sdk/sessions/sess_abc123def456 \
  -H "Authorization: Bearer sentrial_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "success": true,
    "estimatedCost": 0.045
  }'
```

## Error Codes

| Code  | Title                 | Description                             |
| ----- | --------------------- | --------------------------------------- |
| `400` | Bad Request           | Missing required fields or invalid data |
| `401` | Unauthorized          | Invalid or missing API key              |
| `404` | Not Found             | Session ID not found                    |
| `500` | Internal Server Error | Server error, please retry              |

## Next Steps

<CardGroup cols={2}>
  <Card title="Events API" icon="bolt" href="/api/events">
    Track events within sessions.
  </Card>

  <Card title="Python SDK" icon="python" href="/sdk/python">
    Use the SDK for easier integration.
  </Card>
</CardGroup>