Sessions API

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.

Sessions are automatically created when you send messages via Chat Completions API.

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

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`

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.

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

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)

Sessions are automatically sorted by last_update_time (most recent first). Custom sorting is not currently supported.

Response

Status Code: 200 OK

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

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

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

{
  "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`)

Messages are always returned in chronological order (oldest first).

cURL Example

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

GET /api/external/sessions/{session_id}/status

Path Parameters:

Parameter	Type	Required	Description
`session_id`	string	Yes	Session UUID

Response

Status Code: 200 OK

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

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_processing": false
}

When timed out (30 minutes):

{
  "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)

Sessions automatically timeout after 30 minutes of processing.

cURL Example

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

{
  "detail": "Session not found or access denied"
}

{
  "detail": {
    "page_size": ["ensure this value is less than or equal to 100"]
  }
}

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

Chat Completions API

Send messages and create sessions

Authentication

Learn about API key authentication

Rate Limits

Understand rate limiting

​Overview

​Required Scopes

​Endpoints

​List Sessions

​Request

​Response

​Response Fields

​cURL Example

​Get Session Messages

​Request

​Response

​Message Object

​cURL Example

​Get Session Processing Status

​Request

​Response

​Response Fields

​cURL Example

​Error Handling

​Common Errors

​Best Practices

​Next Steps

Chat Completions API

Authentication

Rate Limits

Overview

Required Scopes

Endpoints

List Sessions

Request

Response

Response Fields

cURL Example

Get Session Messages

Request

Response

Message Object

cURL Example

Get Session Processing Status

Request

Response

Response Fields

cURL Example

Error Handling

Common Errors

Best Practices

Next Steps