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.

Building your own product on Junis? Add on_behalf_of to read the sessions of a user you provisioned, and use DELETE to purge their data when they leave. See User Provisioning.

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`
`DELETE /api/external/sessions/{session_id}`	`sessions:delete`

Adding on_behalf_of to any of them also requires users:delegate.

sessions:delete is opt-in and is never part of a default key. Grant it from Dashboard → API Keys → New Key by ticking “Connect users from my own app”.

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
`DELETE`	`/api/external/sessions/{session_id}`	Permanently delete a session and its messages

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)
`on_behalf_of`	string	—	List the sessions of a user your organization provisioned. Requires `users:delegate`. Omit for your own key’s sessions.
`include_hidden`	boolean	`true`	Set to `false` to leave out sessions created with `session_hidden` — useful when the list is shown to the user.

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)
`on_behalf_of`	string	—	Read a session belonging to a user your organization provisioned. Requires `users:delegate`.

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

Query Parameters:

Parameter	Type	Default	Description
`on_behalf_of`	string	—	Check a session belonging to a user your organization provisioned. Requires `users:delegate`.

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"

Delete Session

Permanently delete a session together with its messages and stored state.

This cannot be undone. There is no soft delete and no recovery window.

Request

DELETE /api/external/sessions/{session_id}

Path Parameters:

Parameter	Type	Required	Description
`session_id`	string	Yes	Session UUID

Query Parameters:

Parameter	Type	Default	Description
`on_behalf_of`	string	—	Delete a session belonging to a user your organization provisioned. Requires `users:delegate`.

Response

Status Code: 200 OK

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "deleted": true
}

cURL Example

curl -X DELETE \
  "https://api.junis.ai/api/external/sessions/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: jns_live_YOUR_API_KEY"

Deletions are recorded in your organization’s audit log.

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

​Delete Session

​Request

​Response

​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

Delete Session

Request

Response

cURL Example

Error Handling

Common Errors

Best Practices

Next Steps