---
title: "Create an intern"
method: POST
path: "/interns"
tags: ["Interns"]
---

# Create an intern

`POST /interns`

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](/docs/api-reference/authentication) required.

## Headers

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

## Request body

- CreateInternRequest — Settings for a new intern in an explicit workspace.
  - `description` string, nullable — Free-form description, or null.
  - `instructions` string, nullable — Standing instructions the intern boots with, or null.
  - `name` string, required — Intern name, unique per creator within the workspace.
  - `provision` boolean — Start provisioning during this create operation. Defaults to false.
  - `vault_id` string, uuid — Vault owned by another intern in this workspace to attach as a borrowed vault.
  - `workspace_id` string, uuid, required — Workspace that will own the intern. It must match the API key workspace.

## Response `200`

A completed create operation was replayed.

- Intern — Public lifecycle state and settings for one intern.
  - `attached_vault_id` string, nullable, required — Vault the intern borrows from another intern, or null when it borrows none.
  - `createdAt` string, required — ISO 8601 creation time.
  - `description` string, nullable, required — Free-form description.
  - `hostname` string, nullable, required — Public hostname the intern is reachable at, or null until provisioning has assigned one.
  - `id` string, required — Intern id.
  - `instructions` string, nullable, required — Standing instructions the intern boots with.
  - `lastFailureMessage` string, nullable, required — Why the last provisioning attempt failed, when status is failed.
  - `model` string, nullable, required — OpenRouter model slug the intern runs, or null for the workspace default.
  - `name` string, required — Intern name, unique per creator within a workspace.
  - `progress` object, nullable, required — Active provisioning step, or null once provisioning has settled.
    - `stepLabel` string, required — Human-readable label of the active provisioning step.
    - `stepNumber` integer, required — One-based index of the active step.
    - `totalSteps` integer, required — Number of provisioning steps.
  - `status` 'awaiting_slack_install' | 'queued' | 'provisioning' | 'running' | 'failed' | 'stopped' | 'destroying' | 'destroy_failed', required — Lifecycle status.
  - `updatedAt` string, required — ISO 8601 last update time.
  - `vault_id` string, nullable, required — Vault the intern owns, or null before it has been created.
  - `workspaceId` string, required — Workspace that owns the intern and scopes its secrets.

## Other responses

- `201` — Intern created.
- `400` — The request body is invalid.
- `401` — Missing, unknown or provisioning API key.
- `403` — The key acts as an organization and has no member who can own the intern, or regional access is refused.
- `404` — The caller is outside the Intern API programme, the intern is hidden, or lifecycle writes are disabled.
- `408` — The request exceeded its route deadline.
- `409` — The idempotency key was reused, the member reached the intern limit, or the requested vault cannot be attached.
- `413` — The request body is larger than 1048576 bytes.
- `500` — The request could not be completed.
- `502` — The vault or provisioner did not complete a recoverable create step. Retry the same request.

## Changes

- **2026-09-17** `c3b9702bd9d7` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/interns/post.md)

---

[API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openrouterteam/apis/openrouter-api/revisions/c3b9702bd9d7?raw)