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

# Warmup

> Build an organization/user orchestrator (and optionally one agent) ahead of the first message

## Overview

Junis builds your organization's agents lazily, per **(organization, user)**, on the server that receives the request, and keeps them in memory while they are in use. The first message of a newly provisioned user therefore pays that build before the first token: a fraction of a second for a small squad, several seconds for squads with many tools or integrations.

`POST /v1/warmup` performs that build **without any LLM call** (no tokens, no charge) so the first message finds everything ready. Requests that carry the same API key are routed to the same server, so the warmed instance is the one your next message uses.

<Info>
  **When to call it**: right after provisioning a user ([User Provisioning](/api-reference/user-provisioning)), or after a long idle period. Warmed instances are released after about an hour of inactivity and after server restarts or deployments; calling warmup again is always safe.
</Info>

***

## Endpoint

```
POST https://api.junis.ai/api/external/v1/warmup
```

### Authentication

| Scope | When |
| - | - |
| `orchestrator:invoke` | always |
| `users:delegate` | when `on_behalf_of` is set |
| `agents:invoke` | when `agent_id` is set |

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `on_behalf_of` | string | No | Warm the orchestrator for this provisioned user (same rules as in Chat Completions: active or pending member of your organization). Omit to warm for the API key's own user. |
| `agent_id` | string | No | Also pre-build this agent (UUID of an active agent in your organization). Useful before the first [`POST /agents/{agent_id}/completions`](/api-reference/agents) call or the first `target_agent_id` turn. Unknown/foreign → `404 agent_not_found`, inactive → `400 agent_inactive`. |

### Request Example

```bash cURL theme={null}
curl -X POST https://api.junis.ai/api/external/v1/warmup \
  -H "X-API-Key: jns_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "on_behalf_of": "9f1c…",
    "agent_id": "785aba85-caf1-4e22-8ca9-841093e611d6"
  }'
```

### Response

```json theme={null}
{
  "status": "built",
  "took_ms": 412,
  "organization_id": "603da21e-…",
  "user_id": "9f1c…",
  "sub_agents": 8,
  "tools": 18,
  "agent_id": "785aba85-caf1-4e22-8ca9-841093e611d6",
  "agent_ready": true
}
```

| Field | Type | Description |
| - | - | - |
| `status` | string | `built` — the build ran now (or joined a build already in progress); `warm` — already cached |
| `took_ms` | integer | Time spent building (after validation), in milliseconds |
| `organization_id` | string | Your organization |
| `user_id` | string | The user the orchestrator was warmed for |
| `sub_agents` | integer | Sub-agents attached to the orchestrator |
| `tools` | integer | Tools attached to the orchestrator |
| `agent_id` | string | The pre-built agent, when requested |
| `agent_ready` | boolean | Whether the requested agent was built and cached |

### Errors

| Status | Code | Meaning |
| - | - | - |
| `403` | `insufficient_scopes` | Missing `users:delegate` (with `on_behalf_of`) or `agents:invoke` (with `agent_id`) |
| `403` | `no_subscription` / `invalid_plan` | Same subscription gate as `POST /v1/chat/completions` (Basic or Pro required for the key's user) |
| `402` | `insufficient_credits` | Same credit gate as `POST /v1/chat/completions` (billing user's effective balance is negative) |
| `404` | `agent_not_found` | `agent_id` is not an agent of your organization |
| `400` | `agent_inactive` | The agent exists but is inactive |
| `500` | `internal_error` | The build failed (the next message will try again) |

<Note>
  Warmup is rate-limited like every other External API call. It is idempotent: calling it for an already-warm user returns `status: "warm"` immediately.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.