Chat Completions

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.

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

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`)
`temperature`	number	No	Sampling temperature (0.0 - 2.0)
`max_tokens`	integer	No	Maximum tokens in response
`top_p`	number	No	Nucleus sampling parameter
`frequency_penalty`	number	No	Frequency penalty (-2.0 to 2.0)
`presence_penalty`	number	No	Presence penalty (-2.0 to 2.0)
`stop`	string or array	No	Stop sequences
`n`	integer	No	Number of completions to generate (default: `1`)
`tools`	array	No	Available tools for function calling (keyword-based detection)
`elevenlabs_extra_body`	object	No	ElevenLabs metadata (e.g., `conversation_id` for session continuity)

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": 1699896916,
  "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
  }
}

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`)
`usage`	object	Token usage statistics

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":1699896916,"model":"junis-orchestrator","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1699896916,"model":"junis-orchestrator","choices":[{"index":0,"delta":{"content":"Once"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1699896916,"model":"junis-orchestrator","choices":[{"index":0,"delta":{"content":" upon"},"finish_reason":null}]}

...

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1699896916,"model":"junis-orchestrator","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Key Points:

Each line starts with data:
First chunk contains role
Subsequent chunks contain content deltas
Final chunk has finish_reason
Stream ends with data: [DONE]

Session Management

Junis automatically manages conversation sessions for you.

How Sessions Work

Session Detection

Junis uses smart session detection with the following priority:

ElevenLabs conversation_id (in elevenlabs_extra_body) → Uses or creates session with this ID
Single message → Creates new session
Multiple messages → Uses message hash to match existing sessions (allows conversation continuation)

For ElevenLabs integration: Pass conversation_id in elevenlabs_extra_body to maintain session continuity across calls.

{
  "messages": [...],
  "elevenlabs_extra_body": {
    "conversation_id": "your-unique-conversation-id"
  }
}

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 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
`permission_error`	403	Insufficient permissions	Check API key scopes
`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

API Reference

​Overview

​Endpoint

​Authentication

​Request Format

​Basic Request

​Request Parameters

​Message Format

​Response Format

​Non-Streaming Response

​Response Fields

​Streaming Mode

​Streaming Request

​Streaming Response Format

​Session Management

​How Sessions Work

​Session Detection

​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

Endpoint

Authentication

Request Format

Basic Request

Request Parameters

Message Format

Response Format

Non-Streaming Response

Response Fields

Streaming Mode

Streaming Request

Streaming Response Format

Session Management

How Sessions Work

Session Detection

Viewing Sessions

Function Calling (Tool Use)

Error Handling

Common Errors

Error Types

Best Practices

Response Parameters

Temperature Guide

Next Steps