External API Overview

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:invoke`	Invoke the main orchestrator via chat completions
`agents:list`	List available agents in organization
`agents:invoke`	Invoke individual agents directly
`sessions:read`	Read session history and messages
`rag:upload`	Upload files to RAG Datastore
`rag:read`	Read RAG uploads and DataStores

Available Endpoints

OpenAI-Compatible

Chat Completions

POST /v1/chat/completions - OpenAI-compatible chat API

Agent Management

List Agents

GET /agents - List available agents

Invoke Agent

POST /agents/{agent_id}/completions - Invoke specific agent

Session Management

List Sessions

GET /sessions - List chat sessions

Get Messages

GET /sessions/{session_id}/messages - Get session messages

RAG Knowledge Base

Create DataStore

POST /rag/datastores - Create new DataStore

Upload Files

POST /rag/upload - Upload files to DataStore

List Uploads

GET /rag/uploads - List upload history

List DataStores

GET /rag/datastores - List DataStores

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": 1767261600,
  "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_key`	401	API key is invalid or revoked
`insufficient_credits`	402	Not enough credits for request
`rate_limit_exceeded`	429	Too many requests
`scope_not_allowed`	403	API key lacks required scope
`agent_not_found`	404	Specified agent doesn’t exist

Chat Completions

OpenAI-compatible chat API

Agent API

Individual agent invocation

​Introduction

​Base URL

​Authentication

​API Key Scopes

​Available Endpoints

​OpenAI-Compatible

Chat Completions

​Agent Management

List Agents

Invoke Agent

​Session Management

List Sessions

Get Messages

​RAG Knowledge Base

Create DataStore

Upload Files

List Uploads

List DataStores

​Quick Start

​1. Get Your API Key

​2. Make Your First Call

​3. Parse the Response

​SDK Support

​OpenAI Python SDK

​OpenAI Node.js SDK

​Streaming

​Rate Limits

​Error Handling

​Common Error Codes

​Related

Chat Completions

Agent API

Introduction

Base URL

Authentication

API Key Scopes

Available Endpoints

OpenAI-Compatible

Agent Management

Session Management

RAG Knowledge Base

Quick Start

1. Get Your API Key

2. Make Your First Call

3. Parse the Response

SDK Support

OpenAI Python SDK

OpenAI Node.js SDK

Streaming

Rate Limits

Error Handling

Common Error Codes

Related