Introduction The External API allows you to integrate Junis AI agents into your own applications. Use your API key to invoke agents, manage sessions, and build powerful AI-powered features.
External API requires an active subscription (Basic or Pro). Credits are consumed for each API call.
Base URL https://api.junis.ai/api/external For OpenAI-compatible endpoints:
https://api.junis.ai/api/external/v1 Authentication All External API requests require an API key in the X-API-Key header:
curl -H "X-API-Key: jns_live_xxxxxxxxxxxxxxxx" \ https://api.junis.ai/api/external/v1/chat/completions Never expose your API key in client-side code. Use server-side calls or a backend proxy.
API Key Scopes API keys can be created with specific scopes to limit access:
Scope Description orchestrator:invokeInvoke the main orchestrator via chat completions agents:listList available agents in organization agents:invokeInvoke individual agents directly sessions:readRead session history and messages
Available Endpoints OpenAI-Compatible
Chat Completions POST /v1/chat/completions - OpenAI-compatible chat API
Agent Management Session Management Quick Start 1. Get Your API Key
Go to Admin > API Keys
Click Create API Key
Select required scopes
Copy and securely store the key (shown only once)
2. Make Your First Call curl -X POST https://api.junis.ai/api/external/v1/chat/completions \ -H "X-API-Key: jns_live_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "model": "junis-orchestrator", "messages": [{"role": "user", "content": "Hello, how are you?"}], "stream": false }' 3. Parse the Response { "id" : "cmpl-abc123" , "object" : "chat.completion" , "created" : 1701234567 , "model" : "junis-orchestrator" , "choices" : [{ "index" : 0 , "message" : { "role" : "assistant" , "content" : "Hello! I'm doing well, thank you for asking..." }, "finish_reason" : "stop" }], "usage" : { "prompt_tokens" : 10 , "completion_tokens" : 25 , "total_tokens" : 35 } } SDK Support OpenAI Python SDK import openai client = openai.OpenAI( api_key = "jns_live_your_api_key" , base_url = "https://api.junis.ai/api/external/v1" ) response = client.chat.completions.create( model = "junis-orchestrator" , messages = [{ "role" : "user" , "content" : "Hello!" }] ) print (response.choices[ 0 ].message.content) OpenAI Node.js SDK import OpenAI from 'openai' ; const openai = new OpenAI ({ apiKey: 'jns_live_your_api_key' , baseURL: 'https://api.junis.ai/api/external/v1' }); const response = await openai . chat . completions . create ({ model: 'junis-orchestrator' , messages: [{ role: 'user' , content: 'Hello!' }] }); console . log ( response . choices [ 0 ]. message . content ); Streaming Enable streaming for real-time responses:
stream = client.chat.completions.create( model = "junis-orchestrator" , messages = [{ "role" : "user" , "content" : "Tell me a story" }], stream = True ) for chunk in stream: if chunk.choices[ 0 ].delta.content: print (chunk.choices[ 0 ].delta.content, end = "" ) Rate Limits Plan Requests/min Concurrent requests Basic 60 5 Pro 300 20
Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Error Handling All errors follow a consistent format:
{ "error" : { "message" : "Invalid API key" , "type" : "authentication_error" , "code" : "invalid_api_key" } } Common Error Codes Code Status Description invalid_api_key401 API key is invalid or revoked insufficient_credits402 Not enough credits for request rate_limit_exceeded429 Too many requests scope_not_allowed403 API key lacks required scope agent_not_found404 Specified agent doesn’t exist
