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

# Sessions API

> Retrieve conversation sessions and messages

## Overview

The Sessions API allows you to **retrieve conversation history** and access message details. All sessions are scoped to your organization and the API key creator.

<Info>
  Sessions are automatically created when you send messages via [Chat Completions API](/api-reference/chat-completions).
</Info>

<Warning>
  **Read-Only API**: Sessions API provides read-only access. Session deletion and modification are not currently supported via API.
</Warning>

### Required Scopes

All Sessions API endpoints require specific API key scopes:

| Endpoint                                           | Required Scope      |
| -------------------------------------------------- | ------------------- |
| `GET /api/external/sessions`                       | `sessions:read`     |
| `GET /api/external/sessions/{session_id}/messages` | `sessions:messages` |
| `GET /api/external/sessions/{session_id}/status`   | `sessions:read`     |

<Note>
  When creating an API key in the Admin panel, ensure you enable the appropriate scopes. Without the required scopes, requests will return a `403 Forbidden` error.
</Note>

***

## Endpoints

| Method | Endpoint                                       | Description                      |
| ------ | ---------------------------------------------- | -------------------------------- |
| `GET`  | `/api/external/sessions`                       | List all sessions (paginated)    |
| `GET`  | `/api/external/sessions/{session_id}/messages` | Get session messages (paginated) |
| `GET`  | `/api/external/sessions/{session_id}/status`   | Get session processing status    |

***

## List Sessions

Retrieve all sessions created by your API key.

### Request

```bash theme={null}
GET /api/external/sessions
```

**Query Parameters:**

| Parameter   | Type    | Default | Description               |
| ----------- | ------- | ------- | ------------------------- |
| `page`      | integer | 1       | Page number (1-indexed)   |
| `page_size` | integer | 20      | Items per page (max: 100) |

<Note>
  Sessions are automatically sorted by `last_update_time` (most recent first). Custom sorting is not currently supported.
</Note>

### Response

**Status Code:** `200 OK`

```json theme={null}
{
  "sessions": [
    {
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2026-01-01T10:00:00Z",
      "last_update_time": "2026-01-01T15:30:00Z",
      "is_active": true,
      "message_count": 12
    },
    {
      "session_id": "660f9511-f39c-52e5-b827-557766551111",
      "created_at": "2026-01-01T14:20:00Z",
      "last_update_time": "2026-01-01T16:45:00Z",
      "is_active": false,
      "message_count": 8
    }
  ],
  "total": 45,
  "page": 1,
  "page_size": 20,
  "has_next": true
}
```

### Response Fields

| Field                         | Type    | Description                   |
| ----------------------------- | ------- | ----------------------------- |
| `sessions`                    | array   | Array of session objects      |
| `sessions[].session_id`       | string  | Unique session ID (UUID)      |
| `sessions[].created_at`       | string  | ISO 8601 timestamp            |
| `sessions[].last_update_time` | string  | Last activity timestamp       |
| `sessions[].is_active`        | boolean | Whether session is active     |
| `sessions[].message_count`    | integer | Number of messages in session |
| `total`                       | integer | Total number of sessions      |
| `page`                        | integer | Current page number           |
| `page_size`                   | integer | Items per page                |
| `has_next`                    | boolean | Whether there are more pages  |

### cURL Example

```bash theme={null}
curl -X GET 'https://api.junis.ai/api/external/sessions?page=1&page_size=20' \
  -H "X-API-Key: jns_live_YOUR_API_KEY_HERE"
```

***

## Get Session Messages

Retrieve all messages from a specific session.

### Request

```bash theme={null}
GET /api/external/sessions/{session_id}/messages
```

**Path Parameters:**

| Parameter    | Type   | Required | Description  |
| ------------ | ------ | -------- | ------------ |
| `session_id` | string | Yes      | Session UUID |

**Query Parameters:**

| Parameter   | Type    | Default | Description               |
| ----------- | ------- | ------- | ------------------------- |
| `page`      | integer | 1       | Page number (1-indexed)   |
| `page_size` | integer | 50      | Items per page (max: 200) |

### Response

**Status Code:** `200 OK`

```json theme={null}
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "messages": [
    {
      "event_id": "evt_001",
      "event_type": "user_message",
      "content": "What is Junis?",
      "agent": null,
      "created_at": "2026-01-01T10:00:00Z",
      "visibility": "visible"
    },
    {
      "event_id": "evt_002",
      "event_type": "assistant_message",
      "content": "Junis is a production-ready Multi-Agent AI platform...",
      "agent": "Orchestrator",
      "created_at": "2026-01-01T10:00:05Z",
      "visibility": "visible"
    },
    {
      "event_id": "evt_003",
      "event_type": "user_message",
      "content": "How do I create an agent?",
      "agent": null,
      "created_at": "2026-01-01T10:05:00Z",
      "visibility": "visible"
    },
    {
      "event_id": "evt_004",
      "event_type": "assistant_message",
      "content": "To create an agent, follow these steps...",
      "agent": "Orchestrator",
      "created_at": "2026-01-01T10:05:08Z",
      "visibility": "visible"
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 50,
  "has_next": false
}
```

### Message Object

| Field        | Type           | Description                                        |
| ------------ | -------------- | -------------------------------------------------- |
| `event_id`   | string         | Unique message ID                                  |
| `event_type` | string         | Message type (`user_message`, `assistant_message`) |
| `content`    | string         | Message text content                               |
| `agent`      | string or null | Agent name (for assistant messages)                |
| `created_at` | string         | ISO 8601 timestamp                                 |
| `visibility` | string         | Message visibility (`visible`, `hidden`)           |

<Note>
  Messages are always returned in chronological order (oldest first).
</Note>

### cURL Example

```bash theme={null}
curl -X GET 'https://api.junis.ai/api/external/sessions/550e8400-e29b-41d4-a716-446655440000/messages?page=1&page_size=50' \
  -H "X-API-Key: jns_live_YOUR_API_KEY_HERE"
```

***

## Get Session Processing Status

Check if a session is currently processing a message.

### Request

```bash theme={null}
GET /api/external/sessions/{session_id}/status
```

**Path Parameters:**

| Parameter    | Type   | Required | Description  |
| ------------ | ------ | -------- | ------------ |
| `session_id` | string | Yes      | Session UUID |

### Response

**Status Code:** `200 OK`

```json theme={null}
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_processing": true,
  "started_at": "2026-01-01T15:30:00Z",
  "current_agent": "Orchestrator",
  "elapsed_seconds": 2.5
}
```

**When not processing:**

```json theme={null}
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_processing": false
}
```

**When timed out (30 minutes):**

```json theme={null}
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_processing": false,
  "timed_out": true,
  "message": "Request took too long and was automatically cancelled"
}
```

### Response Fields

| Field             | Type               | Description                                     |
| ----------------- | ------------------ | ----------------------------------------------- |
| `session_id`      | string             | Session UUID                                    |
| `is_processing`   | boolean            | Whether session is currently processing         |
| `started_at`      | string (optional)  | ISO 8601 timestamp (if processing)              |
| `current_agent`   | string (optional)  | Active agent name (if processing)               |
| `elapsed_seconds` | float (optional)   | Time elapsed (if processing)                    |
| `timed_out`       | boolean (optional) | Whether request timed out (if timeout occurred) |
| `message`         | string (optional)  | Status message (if timeout occurred)            |

<Note>
  Sessions automatically timeout after 30 minutes of processing.
</Note>

### cURL Example

```bash theme={null}
curl -X GET 'https://api.junis.ai/api/external/sessions/550e8400-e29b-41d4-a716-446655440000/status' \
  -H "X-API-Key: jns_live_YOUR_API_KEY_HERE"
```

***

## Error Handling

### Common Errors

<ResponseExample>
  ```json 404 Not Found theme={null}
  {
    "detail": "Session not found or access denied"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "detail": {
      "page_size": ["ensure this value is less than or equal to 100"]
    }
  }
  ```
</ResponseExample>

## Best Practices

* **Use Pagination**: Always use pagination with appropriate `page_size` (max: 100 for sessions, 200 for messages) to avoid timeouts
* **Cache Session Data**: Implement caching to reduce API calls (recommended TTL: 5 minutes)
* **Poll Status for Long-Running Requests**: Use the status endpoint to check if a session is still processing
* **Handle Errors**: Check for 404 (session not found) and 400 (invalid parameters) responses

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Chat Completions API" icon="comments" href="/api-reference/chat-completions">
    Send messages and create sessions
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn about API key authentication
  </Card>

  <Card title="Rate Limits" icon="gauge-high" href="/api-reference/rate-limits">
    Understand rate limiting
  </Card>
</CardGroup>