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.
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/sessionsList all sessions (paginated) GET/api/external/sessions/{session_id}/messagesGet session messages (paginated) GET/api/external/sessions/{session_id}/statusGet session processing status
List Sessions Retrieve all sessions created by your API key.
Request GET /api/external/sessions Query Parameters: Parameter Type Default Description pageinteger 1 Page number (1-indexed) page_sizeinteger 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" : "2025-01-10T10:00:00Z" , "last_update_time" : "2025-01-10T15:30:00Z" , "is_active" : true , "message_count" : 12 }, { "session_id" : "660f9511-f39c-52e5-b827-557766551111" , "created_at" : "2025-01-09T14:20:00Z" , "last_update_time" : "2025-01-09T16:45:00Z" , "is_active" : false , "message_count" : 8 } ], "total" : 45 , "page" : 1 , "page_size" : 20 , "has_next" : true } Response Fields Field Type Description sessionsarray Array of session objects sessions[].session_idstring Unique session ID (UUID) sessions[].created_atstring ISO 8601 timestamp sessions[].last_update_timestring Last activity timestamp sessions[].is_activeboolean Whether session is active sessions[].message_countinteger Number of messages in session totalinteger Total number of sessions pageinteger Current page number page_sizeinteger Items per page has_nextboolean 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_idstring Yes Session UUID
Query Parameters: Parameter Type Default Description pageinteger 1 Page number (1-indexed) page_sizeinteger 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" : "2025-01-10T10: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" : "2025-01-10T10:00:05Z" , "visibility" : "visible" }, { "event_id" : "evt_003" , "event_type" : "user_message" , "content" : "How do I create an agent?" , "agent" : null , "created_at" : "2025-01-10T10:05:00Z" , "visibility" : "visible" }, { "event_id" : "evt_004" , "event_type" : "assistant_message" , "content" : "To create an agent, follow these steps..." , "agent" : "Orchestrator" , "created_at" : "2025-01-10T10:05:08Z" , "visibility" : "visible" } ], "total" : 12 , "page" : 1 , "page_size" : 50 , "has_next" : false } Message Object Field Type Description event_idstring Unique message ID event_typestring Message type (user_message, assistant_message) contentstring Message text content agentstring or null Agent name (for assistant messages) created_atstring ISO 8601 timestamp visibilitystring 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_idstring Yes Session UUID
Response Status Code: 200 OK{ "session_id" : "550e8400-e29b-41d4-a716-446655440000" , "is_processing" : true , "started_at" : "2025-01-10T15: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_idstring Session UUID is_processingboolean Whether session is currently processing started_atstring (optional) ISO 8601 timestamp (if processing) current_agentstring (optional) Active agent name (if processing) elapsed_secondsfloat (optional) Time elapsed (if processing) timed_outboolean (optional) Whether request timed out (if timeout occurred) messagestring (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
400 Bad Request
{ "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 timeoutsCache 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 processingHandle Errors : Check for 404 (session not found) and 400 (invalid parameters) responses
Next Steps 