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.

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.

---

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

404 Not Found

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

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