Sign in
Interns

Create an intern

Creates an intern in an explicit workspace. The operation also creates its private vault. It can start provisioning immediately or wait for a later provision call. A retry with the same idempotency key and body resumes unfinished work. The request body is capped at 1048576 bytes and a larger body is refused with 413. The API key selects the caller, workspace and visible interns. There is no default workspace fallback. Requests on regional hostnames such as eu.openrouter.ai are refused. API key required.

post/interns

Headers

Idempotency-Keystring

Key that makes retries resume the same create operation. Without one, the server derives a stable key from the request body.

Example:create-research-assistant-2026-09-16

Key that makes retries resume the same create operation. Without one, the server derives a stable key from the request body.

Request body

descriptionstring nullable

Free-form description, or null.

instructionsstring nullable

Standing instructions the intern boots with, or null.

namestring required

Intern name, unique per creator within the workspace.

provisionboolean

Start provisioning during this create operation. Defaults to false.

vault_idstring uuid

Vault owned by another intern in this workspace to attach as a borrowed vault.

workspace_idstring uuid

Workspace that will own the intern. Defaults to the workspace the API key resolves to. When given, it must match the API key workspace.

Example request

{
  "name": "research-assistant",
  "provision": true,
  "workspace_id": "89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb"
}

Response

A completed create operation was replayed.

attached_vault_idstring nullable required

Vault the intern borrows from another intern, or null when it borrows none.

created_atstring required

ISO 8601 creation time.

descriptionstring nullable required

Free-form description.

hostnamestring nullable required

Public hostname the intern is reachable at, or null until provisioning has assigned one.

idstring required

Intern id.

instructionsstring nullable required

Standing instructions the intern boots with.

last_failure_messagestring nullable required

Why the last provisioning attempt failed, when status is failed.

modelstring nullable required

OpenRouter model slug the intern runs, or null for the workspace default.

namestring required

Intern name, unique per creator within a workspace.

status'awaiting_slack_install' | 'queued' | 'provisioning' | 'running' | 'failed' | 'stopped' | 'destroying' | 'destroy_failed' required

Lifecycle status.

updated_atstring required

ISO 8601 last update time.

vault_idstring nullable required

Vault the intern owns, or null before it has been created.

workspace_idstring required

Workspace that owns the intern and scopes its secrets.

Example response

{
  "attached_vault_id": null,
  "created_at": "2026-09-16T08:30:00.000Z",
  "description": "Researches customer questions",
  "hostname": "research-assistant.openrouter.ai",
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "instructions": null,
  "last_failure_message": null,
  "model": "openai/gpt-5.4",
  "name": "research-assistant",
  "progress": null,
  "status": "running",
  "updated_at": "2026-09-16T08:45:00.000Z",
  "vault_id": "b431c59d-6eed-41ac-bc89-9a89be79a121",
  "workspace_id": "89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb"
}

Changes