Warmup - Junis

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.

When to call it: right after provisioning a user (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.

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` call or the first `target_agent_id` turn. Unknown/foreign → `404 agent_not_found`, inactive → `400 agent_inactive`.

Request Example

cURL

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

{
  "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)

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

​Overview

​Endpoint

​Authentication

​Request Body

​Request Example

​Response

​Errors

Overview

Endpoint

Authentication

Request Body

Request Example

Response

Errors