Chat Completions

{
  "error": {
    "message": "Invalid request: 'messages' field is required",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "missing_required_field"
  }
}

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "Insufficient credits. Current balance: $-5.00. Please add credits to continue.",
    "type": "insufficient_credits",
    "code": "insufficient_credits"
  },
  "credit_balance": -5.0,
  "effective_balance": -5.0,
  "can_use_api": false
}

{
  "error": {
    "message": "Basic or Pro subscription required. Please visit /subscription to start a subscription.",
    "type": "subscription_required",
    "code": "no_subscription"
  },
  "has_subscription": false,
  "required_plans": ["basic_monthly", "pro_monthly"]
}

{
  "error": {
    "message": "External API is only available for Basic or Pro subscribers.",
    "type": "invalid_subscription_plan",
    "code": "invalid_plan"
  },
  "current_plan": "token_30",
  "required_plans": ["basic_monthly", "pro_monthly"]
}

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: 60 requests per minute",
  "limit": 60,
  "window": "minute",
  "reset_at": 1767261600,
  "retry_after": 45
}

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: 3000 requests per hour",
  "limit": 3000,
  "window": "hour",
  "reset_at": 1767265200,
  "retry_after": 1800
}

{
  "error": {
    "message": "Failed to process request: Internal error",
    "type": "api_error",
    "code": "internal_error"
  }
}

{
  "error": {
    "message": "Invalid request: 'messages' field is required",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "missing_required_field"
  }
}

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "Insufficient credits. Current balance: $-5.00. Please add credits to continue.",
    "type": "insufficient_credits",
    "code": "insufficient_credits"
  },
  "credit_balance": -5.0,
  "effective_balance": -5.0,
  "can_use_api": false
}

{
  "error": {
    "message": "Basic or Pro subscription required. Please visit /subscription to start a subscription.",
    "type": "subscription_required",
    "code": "no_subscription"
  },
  "has_subscription": false,
  "required_plans": ["basic_monthly", "pro_monthly"]
}

{
  "error": {
    "message": "External API is only available for Basic or Pro subscribers.",
    "type": "invalid_subscription_plan",
    "code": "invalid_plan"
  },
  "current_plan": "token_30",
  "required_plans": ["basic_monthly", "pro_monthly"]
}

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: 60 requests per minute",
  "limit": 60,
  "window": "minute",
  "reset_at": 1767261600,
  "retry_after": 45
}

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: 3000 requests per hour",
  "limit": 3000,
  "window": "hour",
  "reset_at": 1767265200,
  "retry_after": 1800
}

{
  "error": {
    "message": "Failed to process request: Internal error",
    "type": "api_error",
    "code": "internal_error"
  }
}

Overview

The Chat Completions API is fully compatible with OpenAI’s API format, allowing you to use the OpenAI Python SDK, JavaScript SDK, or any OpenAI-compatible client.

Model Parameter (Optional): The model parameter is optional and primarily for SDK compatibility. Your organization’s orchestrator agent automatically uses the configured LLM model.If you’re using an OpenAI SDK that requires the model parameter, you can pass any value (e.g., "junis-orchestrator") for compatibility.

Prerequisites

Subscription Required: This API is only available for Basic or Pro subscribers.If you don’t have an active subscription, you’ll receive a 403 Forbidden error. Visit junis.ai/subscription to start a plan.

Endpoint

POST https://api.junis.ai/api/external/v1/chat/completions

Authentication

Include your API key in the X-API-Key header:

X-API-Key: jns_live_YOUR_API_KEY_HERE

Required Scope: orchestrator:invoke (orchestrator:stream for stream: true, agents:invoke when target_agent_id is set) See Authentication for details.

Request Format

Basic Request

cURL

curl -X POST https://api.junis.ai/api/external/v1/chat/completions \
  -H "X-API-Key: jns_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is Junis?"}
    ]
  }'

Request Parameters

Parameter	Type	Required	Description
`messages`	array	Yes	Array of message objects (OpenAI format)
`stream`	boolean	No	Enable streaming mode (default: `false`)
`session_id`	string	No	Session ID to continue conversation (creates new if not provided)
`on_behalf_of`	string	No	Act on behalf of this Junis user ID. Requires the `users:delegate` scope, and the target must be an active or pending member of the key’s organization. Session/message/memory ownership goes to the target user; subscription checks and credit charges stay with the API key’s backing user. Omitted → behavior identical to today.
`session_hidden`	boolean	No	Create the session as hidden (or update the flag when explicitly passed while reusing a session you own). Hidden sessions are excluded from user-facing session lists (web sidebar, admin session list) but remain fetchable by `session_id`. Omitted → sessions are visible as today.
`extra_context`	string	No	Per-request context or instructions for this turn only (max 65,536 chars). Delivered as a non-persistent trailing block to the orchestrator and to the agent that answers — never stored in the session, never merged into the system instruction. Omitted → behavior identical to today.
`target_agent_id`	string	No	Route this turn directly to the given agent (UUID of an active agent in your organization, normally a sub-agent of the orchestrator) and skip the orchestrator’s routing LLM call. Requires the `agents:invoke` scope. Unknown or foreign id → `404 agent_not_found`; inactive → `400 agent_inactive`. Later turns may omit it — the session continues with the agent that answered last. See Low-latency first turn.

Delegation (on_behalf_of) is designed for partner services that provision end-user accounts via User Provisioning. Pending members are allowed so provisioned users work before their first login.

Message Format

Messages follow the OpenAI format:

{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hi! How can I help you?"},
    {"role": "user", "content": "Tell me about Junis."}
  ]
}

Role Types:

system: System instructions (optional, rarely needed with Junis)
user: User messages
assistant: Assistant responses (for conversation context)
tool: Tool call results (for function calling)

Response Format

Non-Streaming Response

Status Code: 200 OK Response Body:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1767261600,
  "model": "junis-orchestrator",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Junis is a production-ready Multi-Agent AI platform..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 42,
    "total_tokens": 57
  },
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Fields

Field	Type	Description
`id`	string	Unique completion ID
`object`	string	Object type (always `"chat.completion"`)
`created`	integer	Unix timestamp
`model`	string	Model used
`choices`	array	Array of completion choices
`choices[].message`	object	Generated message
`choices[].message.role`	string	Always `"assistant"`
`choices[].message.content`	string	Response text
`choices[].finish_reason`	string	Reason for completion (`stop`, `length`, `tool_calls`, `content_filter`)
`usage`	object	Token usage statistics
`session_id`	string	Session ID for continuing the conversation

Streaming Mode

Enable real-time token-by-token streaming with stream: true.

Streaming Request

cURL

curl -N -X POST https://api.junis.ai/api/external/v1/chat/completions \
  -H "X-API-Key: jns_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Tell me a story"}],
    "stream": true
  }'

Streaming Response Format

Server-Sent Events (SSE) format:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1767261600,"model":"junis-orchestrator","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}],"session_id":"550e8400-e29b-41d4-a716-446655440000"}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1767261600,"model":"junis-orchestrator","choices":[{"index":0,"delta":{"content":"Once"},"finish_reason":null}],"session_id":"550e8400-e29b-41d4-a716-446655440000"}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1767261600,"model":"junis-orchestrator","choices":[{"index":0,"delta":{"content":" upon"},"finish_reason":null}],"session_id":"550e8400-e29b-41d4-a716-446655440000"}

...

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1767261600,"model":"junis-orchestrator","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"session_id":"550e8400-e29b-41d4-a716-446655440000"}

data: [DONE]

Key Points:

Each line starts with data:
First chunk contains role
Subsequent chunks contain content deltas
Final chunk has finish_reason
Every chunk includes session_id for conversation continuity
Stream ends with data: [DONE]
Lines starting with : (for example : keepalive) are SSE comments sent every 15 seconds while the server is still preparing the answer (including the first-time build of your organization’s agents). Standard SSE/OpenAI clients ignore them.

Low-latency first turn: direct routing, warmup, per-request context

The first message of a new session normally costs one extra LLM call: the orchestrator reads the request and decides which agent should answer (transfer_to_agent). Measured in production this routing call takes about 2 seconds (p50) before the answering agent even starts. Later turns in the same session skip it — Junis resumes the agent that answered last. If your application already knows which agent should answer (for example a fixed “counselor” or “support” agent), you can skip the routing call on the first turn too.

`target_agent_id` — skip the routing call

cURL

curl -N -X POST https://api.junis.ai/api/external/v1/chat/completions \
  -H "X-API-Key: jns_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "My child had a hard time at school today"}],
    "on_behalf_of": "9f1c…",
    "extra_context": "Child: 7 years old, recently changed schools",
    "target_agent_id": "785aba85-caf1-4e22-8ca9-841093e611d6",
    "stream": true
  }'

Rule	Detail
Value	UUID of an active agent in your organization (use the `agent_id` from `GET /agents`). Normally a sub-agent of your orchestrator.
Scope	`agents:invoke` in addition to `orchestrator:invoke` (the same permission as `POST /agents/{agent_id}/completions`). Default keys include both.
Validation	Happens before the session is created, so a wrong id never leaves an empty session behind. Unknown/foreign/global id → `404 agent_not_found`, inactive → `400 agent_inactive`.
What the agent receives	On a `target_agent_id` turn the target agent acts as the orchestrator for that turn, so it receives the trailing block the orchestrator would have received: the user’s memory plus `extra_context`.
Later turns	You may omit the field — the session continues with the agent that answered last. Sending it on every turn gives the same result.
Edge cases	If the target is not part of the orchestrator’s tree, the next turn without the field is routed by the orchestrator again. If the last responder is a child of a Sequential/Parallel/Loop agent, every turn is routed by the orchestrator (ADK rule).

POST /agents/{agent_id}/completions gives the same effect (no routing call). target_agent_id lets you keep the OpenAI-compatible body, files, and session rules of this endpoint.

`extra_context` — context for this turn only

extra_context is appended as a non-persistent trailing block after the conversation, for this request only. It is never written to the session and never merged into the system instruction, so it cannot pollute later turns or break prompt caching. Since October 2026 it is delivered to the agent that actually answers (orchestrator-routed sub-agent, target_agent_id target, or /agents/{agent_id}/completions), not only to the orchestrator.

Maximum 65,536 characters (422 if exceeded).
It counts as uncached input tokens on every call that receives it — send what the turn needs, not your whole database.
If your organization prefers the previous behavior (context on the orchestrator call only), contact us and we will turn off delivery to the answering agent for your organization. Sub-agent requests then match the pre-October behavior byte for byte. Note that on target_agent_id turns the orchestrator does not run, so with delivery turned off no model call receives extra_context (or the user’s memory) on those turns — the same as before October.

Warmup — build the agents before the first message

Your organization’s agents are built lazily per (organization, user) on the server that receives the request, so the first message of a newly provisioned user pays that build (fractions of a second for small squads, several seconds for squads with many tools). Call POST /v1/warmup right after provisioning the user and the first message finds everything ready.

Multi-Agent Events

For Advanced Integrations: Junis streams additional agent lifecycle events alongside standard OpenAI chunks. These events have no choices field, so standard OpenAI SDKs automatically ignore them - ensuring 100% backward compatibility.Parse these events to build rich UIs that show which agents are processing your request.

Event Types

Event	Description	Fields
`agent_started`	Agent begins processing	`agent`, `agent_type`, `depth`, `parent_agent`
`agent_completed`	Agent finishes processing	`agent`, `duration_ms`
`agent_routing`	Transition between agents	`from_agent`, `to_agent`
`token_agent`	Which agent produced the token	`agent`
`tool_started`	Tool execution begins	`tool_name`, `tool_id`, `agent_name`
`tool_completed`	Tool execution ends	`tool_name`, `tool_id`, `agent_name`
`payment_required`	Payment needed to continue	`message`, `agent_name`, `nonce`, `network`, `total_amount`

SSE Stream Example (Multi-Agent)

data: {"event":"agent_started","agent":"researcher","agent_type":"LLM_AGENT","depth":1,"timestamp":"2026-01-01T10:00:00Z"}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"Based on"}}],"session_id":"..."}

data: {"event":"token_agent","agent":"researcher","timestamp":"2026-01-01T10:00:00Z"}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":" my research"}}],"session_id":"..."}

data: {"event":"agent_completed","agent":"researcher","duration_ms":1523,"timestamp":"2026-01-01T10:00:01Z"}

data: {"event":"agent_routing","from_agent":"researcher","to_agent":"writer","timestamp":"2026-01-01T10:00:01Z"}

data: {"event":"agent_started","agent":"writer","agent_type":"LLM_AGENT","depth":1,"timestamp":"2026-01-01T10:00:01Z"}

...

data: [DONE]

Parsing Agent Events (Python)

import json
import httpx

async def stream_with_agent_events(prompt: str, api_key: str):
    """Stream response and track agent events."""
    async with httpx.AsyncClient() as client:
        async with client.stream(
            "POST",
            "https://api.junis.ai/api/external/v1/chat/completions",
            headers={"X-API-Key": api_key},
            json={"messages": [{"role": "user", "content": prompt}], "stream": True}
        ) as response:
            current_agent = None
            agent_durations = {}

            async for line in response.aiter_lines():
                if not line.startswith("data: "):
                    continue
                data_str = line[6:]
                if data_str == "[DONE]":
                    break

                data = json.loads(data_str)

                # Agent event (no 'choices' field)
                if "event" in data and "choices" not in data:
                    event = data["event"]

                    if event == "agent_started":
                        current_agent = data["agent"]
                        print(f"🚀 Agent started: {current_agent}")

                    elif event == "agent_completed":
                        agent = data["agent"]
                        duration = data.get("duration_ms", 0)
                        agent_durations[agent] = duration
                        print(f"✅ Agent completed: {agent} ({duration}ms)")

                    elif event == "agent_routing":
                        print(f"🔄 Routing: {data['from_agent']} → {data['to_agent']}")

                # Standard OpenAI chunk (has 'choices' field)
                elif "choices" in data:
                    content = data["choices"][0].get("delta", {}).get("content", "")
                    if content:
                        print(content, end="", flush=True)

            print(f"\n\n📊 Agent performance: {agent_durations}")

Parallel Agent Support

When multiple agents run concurrently (Parallel Agent), use token_agent events to correctly attribute tokens:

agent_buffers = {}  # Per-agent content buffers
last_token_agent = None

for event in stream:
    if event.get("event") == "token_agent":
        last_token_agent = event["agent"]

    elif "choices" in event:
        content = event["choices"][0].get("delta", {}).get("content", "")
        if content and last_token_agent:
            if last_token_agent not in agent_buffers:
                agent_buffers[last_token_agent] = ""
            agent_buffers[last_token_agent] += content

# Result: {"researcher": "Research content...", "analyst": "Analysis content..."}

When to use agent events:

Build agent pipeline visualizations
Track per-agent performance metrics
Handle Parallel Agent outputs separately
Debug multi-agent workflows

Session Management

Junis supports explicit session management via session_id parameter, allowing you to control conversation context precisely.

How Sessions Work

Session ID Usage

Recommended: Always capture the session_id from the first response and include it in subsequent requests to maintain conversation context.

Behavior:

Request	Result
No `session_id`	Creates a new session and returns `session_id` in response
With `session_id` (existing)	Uses the existing session (same chat room)
With `session_id` (new ID)	Creates a new session with the provided ID

Example: Continuing a Conversation

import requests

API_KEY = "jns_live_YOUR_API_KEY_HERE"
BASE_URL = "https://api.junis.ai/api/external/v1/chat/completions"

# First request - no session_id
response1 = requests.post(BASE_URL,
    headers={"X-API-Key": API_KEY},
    json={"messages": [{"role": "user", "content": "Hello!"}]}
)
session_id = response1.json()["session_id"]  # Capture session_id

# Second request - with session_id (continues conversation)
response2 = requests.post(BASE_URL,
    headers={"X-API-Key": API_KEY},
    json={
        "messages": [{"role": "user", "content": "What did I just say?"}],
        "session_id": session_id  # Use captured session_id
    }
)
# Response will have context from the first message

Viewing Sessions

Retrieve your sessions via the Sessions API:

curl -X GET https://api.junis.ai/api/external/sessions \
  -H "X-API-Key: jns_live_YOUR_API_KEY_HERE"

See Sessions API for details.

Function Calling (Tool Use)

Current Implementation: Tool calling uses keyword pattern matching, not LLM-native function calling.Supported tools:

end_call: Detects phrases like “안녕히”, “감사합니다”, “goodbye”
transfer_call: Detects phrases like “상담원 연결”, “전화 연결”, “connect agent”

Full LLM-native function calling support is in development.

When a supported keyword is detected in the assistant’s response, the API returns a tool_calls object with finish_reason: "tool_calls".

Error Handling

Common Errors

{
  "error": {
    "message": "Invalid request: 'messages' field is required",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "missing_required_field"
  }
}

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "message": "Insufficient credits. Current balance: $-5.00. Please add credits to continue.",
    "type": "insufficient_credits",
    "code": "insufficient_credits"
  },
  "credit_balance": -5.0,
  "effective_balance": -5.0,
  "can_use_api": false
}

{
  "error": {
    "message": "Basic or Pro subscription required. Please visit /subscription to start a subscription.",
    "type": "subscription_required",
    "code": "no_subscription"
  },
  "has_subscription": false,
  "required_plans": ["basic_monthly", "pro_monthly"]
}

{
  "error": {
    "message": "External API is only available for Basic or Pro subscribers.",
    "type": "invalid_subscription_plan",
    "code": "invalid_plan"
  },
  "current_plan": "token_30",
  "required_plans": ["basic_monthly", "pro_monthly"]
}

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: 60 requests per minute",
  "limit": 60,
  "window": "minute",
  "reset_at": 1767261600,
  "retry_after": 45
}

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: 3000 requests per hour",
  "limit": 3000,
  "window": "hour",
  "reset_at": 1767265200,
  "retry_after": 1800
}

{
  "error": {
    "message": "Failed to process request: Internal error",
    "type": "api_error",
    "code": "internal_error"
  }
}

Error Types

Error Type	Status Code	Description	Action
`invalid_request_error`	400	Malformed request	Check request format
`authentication_error`	401	Invalid API key	Verify API key
`insufficient_credits`	402	Credit balance below zero	Add credits at /subscription
`subscription_required`	403	No active subscription	Subscribe to Basic or Pro plan
`invalid_subscription_plan`	403	Plan doesn’t include API access	Upgrade to Basic or Pro plan
`rate_limit_error`	429	Too many requests	Implement exponential backoff
`api_error`	500	Server error	Retry with exponential backoff

Best Practices

Use Streaming: Enable stream: true for long responses to provide real-time feedback
Handle Rate Limits: Implement exponential backoff when hitting rate limits (see error codes above)
Keep Message History Concise: Trim old messages to avoid token limits (keep last 10-20 messages)
Secure API Keys: Never hardcode API keys; use environment variables
Log Requests: Log requests and responses for debugging and monitoring

Response Parameters

Temperature Guide

Use Case	Recommended Temperature
Factual Q&A	0.0 - 0.3
General chat	0.5 - 0.7
Creative writing	0.8 - 1.0
Code generation	0.0 - 0.2

Next Steps

Sessions API

Retrieve and manage conversation sessions

Error Codes

Complete error reference

Rate Limits

Understand rate limiting

​Overview

​Prerequisites

​Endpoint

​Authentication

​Request Format

​Basic Request

​Request Parameters

​Message Format

​Response Format

​Non-Streaming Response

​Response Fields

​Streaming Mode

​Streaming Request

​Streaming Response Format

​Low-latency first turn: direct routing, warmup, per-request context

​target_agent_id — skip the routing call

​extra_context — context for this turn only

​Warmup — build the agents before the first message

​Multi-Agent Events

​Event Types

​SSE Stream Example (Multi-Agent)

​Parsing Agent Events (Python)

​Parallel Agent Support

​Session Management

​How Sessions Work

​Session ID Usage

​Example: Continuing a Conversation

​Viewing Sessions

​Function Calling (Tool Use)

​Error Handling

​Common Errors

​Error Types

​Best Practices

​Response Parameters

​Temperature Guide

​Next Steps

Sessions API

Error Codes

Rate Limits

Overview

Prerequisites

Endpoint

Authentication

Request Format

Basic Request

Request Parameters

Message Format

Response Format

Non-Streaming Response

Response Fields

Streaming Mode

Streaming Request

Streaming Response Format

Low-latency first turn: direct routing, warmup, per-request context

`target_agent_id` — skip the routing call

`extra_context` — context for this turn only

Warmup — build the agents before the first message

Multi-Agent Events

Event Types

SSE Stream Example (Multi-Agent)

Parsing Agent Events (Python)

Parallel Agent Support

Session Management

How Sessions Work

Session ID Usage

Example: Continuing a Conversation

Viewing Sessions

Function Calling (Tool Use)

Error Handling

Common Errors

Error Types

Best Practices

Response Parameters

Temperature Guide

Next Steps