> ## Documentation Index
> Fetch the complete documentation index at: https://docs.junis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  External API requires an active subscription (Basic or Pro). Credits are consumed for each API call.
</Info>

***

## 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:

```bash theme={null}
curl -H "X-API-Key: jns_live_xxxxxxxxxxxxxxxx" \
     https://api.junis.ai/api/external/v1/chat/completions
```

<Warning>
  Never expose your API key in client-side code. Use server-side calls or a backend proxy.
</Warning>

***

## 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

<Card title="Chat Completions" icon="comments" href="/api-reference/chat-completions">
  `POST /v1/chat/completions` - OpenAI-compatible chat API
</Card>

### Agent Management

<CardGroup cols={2}>
  <Card title="List Agents" icon="list" href="/api-reference/agents">
    `GET /agents` - List available agents
  </Card>

  <Card title="Invoke Agent" icon="robot" href="/api-reference/agents">
    `POST /agents/{agent_id}/completions` - Invoke specific agent
  </Card>
</CardGroup>

### Session Management

<CardGroup cols={2}>
  <Card title="List Sessions" icon="clock" href="/api-reference/sessions">
    `GET /sessions` - List chat sessions
  </Card>

  <Card title="Get Messages" icon="message" href="/api-reference/sessions">
    `GET /sessions/{session_id}/messages` - Get session messages
  </Card>
</CardGroup>

### RAG Knowledge Base

<CardGroup cols={2}>
  <Card title="Create DataStore" icon="database" href="/api-reference/rag">
    `POST /rag/datastores` - Create new DataStore
  </Card>

  <Card title="Upload Files" icon="upload" href="/api-reference/rag">
    `POST /rag/upload` - Upload files to DataStore
  </Card>

  <Card title="List Uploads" icon="list" href="/api-reference/rag">
    `GET /rag/uploads` - List upload history
  </Card>

  <Card title="List DataStores" icon="folder" href="/api-reference/rag">
    `GET /rag/datastores` - List DataStores
  </Card>
</CardGroup>

***

## 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

```bash theme={null}
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

```json theme={null}
{
  "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

```python theme={null}
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

```javascript theme={null}
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:

```python theme={null}
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                  |

<Note>
  Rate limit headers are included in all responses: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
</Note>

***

## Error Handling

All errors follow a consistent format:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Chat Completions" icon="comments" href="/api-reference/chat-completions">
    OpenAI-compatible chat API
  </Card>

  <Card title="Agent API" icon="robot" href="/api-reference/agents">
    Individual agent invocation
  </Card>
</CardGroup>