External API Overview

Integrate Junis AI agents into your applications

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

1. Go to Admin > API Keys
2. Click Create API Key
3. Select required scopes
4. 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

---

Related

Chat Completions

OpenAI-compatible chat API

Agent API

Individual agent invocation