> ## Documentation Index > Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Interns > Create, inspect, update, provision, suspend and delete OpenRouter interns through an API key, and talk to them: the chat route streams OpenAI-compatible completions from one intern, pausing as an `openrouter.provide_input` tool call when the intern needs your permission or an answer. Available to interns programme members; other callers receive 404. See https://openrouter.ai/docs/guides/ori/intern-chat. ## Overview Create, inspect, update, provision, suspend and delete OpenRouter interns through an API key, and talk to them: the chat route streams OpenAI-compatible completions from one intern, pausing as an `openrouter.provide_input` tool call when the intern needs your permission or an answer. Available to interns programme members; other callers receive 404. See [https://openrouter.ai/docs/guides/ori/intern-chat](https://openrouter.ai/docs/guides/ori/intern-chat). ### Available Operations * [list\_interns](#list_interns) - List interns * [create\_intern](#create_intern) - Create an intern * [delete\_intern](#delete_intern) - Delete an intern * [get\_intern](#get_intern) - Get an intern * [update\_intern](#update_intern) - Update an intern * [provision\_intern](#provision_intern) - Provision an intern * [suspend\_intern](#suspend_intern) - Suspend an intern * [chat](#chat) - Stream a chat completion with an intern ## list\_interns Lists interns visible to the authenticated key, newest first. Filter by workspace and one or more lifecycle statuses. 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/client-sdks/python/docs/api-reference/authentication) required. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", api_key=os.getenv("OPENROUTER_API_KEY", ""), ) as open_router: res = open_router.interns.list_interns() # Handle response print(res) ``` ### Parameters | Parameter | Type | Required | Description | Example | | -------------------------- | ------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `http_referer` | *Optional\[str]* | :heavy\_minus\_sign: | The app identifier should be your app's URL and is used as the primary identifier for rankings.
This is used to track API usage per application.
| | | `x_open_router_title` | *Optional\[str]* | :heavy\_minus\_sign: | The app display name allows you to customize how your app appears in OpenRouter's dashboard.
| | | `x_open_router_categories` | *Optional\[str]* | :heavy\_minus\_sign: | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.
| | | `limit` | *Optional\[int]* | :heavy\_minus\_sign: | Maximum number of interns to return, from 1 through 500. | 50 | | `status` | List\[[operations.Status](../../operations/status.mdx)] | :heavy\_minus\_sign: | Comma-separated lifecycle statuses to include. | \[
"queued",
"running"
] | | `workspace_id` | *Optional\[str]* | :heavy\_minus\_sign: | Only return interns in this workspace. It must match the API key workspace. | 89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb | | `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[components.InternListResponse](../../components/internlistresponse.mdx)** ### Errors | Error Type | Status Code | Content Type | | ----------------------------- | ----------------------- | ---------------- | | errors.InternLifecycleError | 400, 401, 403, 404, 408 | application/json | | errors.InternLifecycleError | 500 | application/json | | errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* | ## create\_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](/docs/client-sdks/python/docs/api-reference/authentication) required. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", api_key=os.getenv("OPENROUTER_API_KEY", ""), ) as open_router: res = open_router.interns.create_intern(name="research-assistant", workspace_id="89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb", provision=True) # Handle response print(res) ``` ### Parameters | Parameter | Type | Required | Description | Example | | -------------------------- | ------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `name` | *str* | :heavy\_check\_mark: | Intern name, unique per creator within the workspace. | | | `workspace_id` | *str* | :heavy\_check\_mark: | Workspace that will own the intern. It must match the API key workspace. | | | `http_referer` | *Optional\[str]* | :heavy\_minus\_sign: | The app identifier should be your app's URL and is used as the primary identifier for rankings.
This is used to track API usage per application.
| | | `x_open_router_title` | *Optional\[str]* | :heavy\_minus\_sign: | The app display name allows you to customize how your app appears in OpenRouter's dashboard.
| | | `x_open_router_categories` | *Optional\[str]* | :heavy\_minus\_sign: | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.
| | | `idempotency_key` | *Optional\[str]* | :heavy\_minus\_sign: | Key that makes retries resume the same create operation. Without one, the server derives a stable key from the request body. | create-research-assistant-2026-09-16 | | `description` | *OptionalNullable\[str]* | :heavy\_minus\_sign: | Free-form description, or null. | | | `instructions` | *OptionalNullable\[str]* | :heavy\_minus\_sign: | Standing instructions the intern boots with, or null. | | | `provision` | *Optional\[bool]* | :heavy\_minus\_sign: | Start provisioning during this create operation. Defaults to false. | | | `vault_id` | *Optional\[str]* | :heavy\_minus\_sign: | Vault owned by another intern in this workspace to attach as a borrowed vault. | | | `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[components.Intern](../../components/intern.mdx)** ### Errors | Error Type | Status Code | Content Type | | ----------------------------- | --------------------------------- | ---------------- | | errors.InternLifecycleError | 400, 401, 403, 404, 408, 409, 413 | application/json | | errors.InternLifecycleError | 500, 502 | application/json | | errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* | ## delete\_intern Starts safe teardown of the intern, its runtime and its private vault. 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/client-sdks/python/docs/api-reference/authentication) required. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", api_key=os.getenv("OPENROUTER_API_KEY", ""), ) as open_router: res = open_router.interns.delete_intern(intern_id="7c9e6679-7425-40de-944b-e07fc1f90ae7") # Handle response print(res) ``` ### Parameters | Parameter | Type | Required | Description | Example | | -------------------------- | ------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `intern_id` | *str* | :heavy\_check\_mark: | ID of an intern visible to the authenticated API key. | 7c9e6679-7425-40de-944b-e07fc1f90ae7 | | `http_referer` | *Optional\[str]* | :heavy\_minus\_sign: | The app identifier should be your app's URL and is used as the primary identifier for rankings.
This is used to track API usage per application.
| | | `x_open_router_title` | *Optional\[str]* | :heavy\_minus\_sign: | The app display name allows you to customize how your app appears in OpenRouter's dashboard.
| | | `x_open_router_categories` | *Optional\[str]* | :heavy\_minus\_sign: | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.
| | | `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[components.DeleteInternResponse](../../components/deleteinternresponse.mdx)** ### Errors | Error Type | Status Code | Content Type | | ----------------------------- | ----------------------- | ---------------- | | errors.InternLifecycleError | 401, 403, 404, 408, 409 | application/json | | errors.InternLifecycleError | 500, 502 | application/json | | errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* | ## get\_intern Returns the public lifecycle state and settings for one visible intern. 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/client-sdks/python/docs/api-reference/authentication) required. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", api_key=os.getenv("OPENROUTER_API_KEY", ""), ) as open_router: res = open_router.interns.get_intern(intern_id="7c9e6679-7425-40de-944b-e07fc1f90ae7") # Handle response print(res) ``` ### Parameters | Parameter | Type | Required | Description | Example | | -------------------------- | ------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `intern_id` | *str* | :heavy\_check\_mark: | ID of an intern visible to the authenticated API key. | 7c9e6679-7425-40de-944b-e07fc1f90ae7 | | `http_referer` | *Optional\[str]* | :heavy\_minus\_sign: | The app identifier should be your app's URL and is used as the primary identifier for rankings.
This is used to track API usage per application.
| | | `x_open_router_title` | *Optional\[str]* | :heavy\_minus\_sign: | The app display name allows you to customize how your app appears in OpenRouter's dashboard.
| | | `x_open_router_categories` | *Optional\[str]* | :heavy\_minus\_sign: | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.
| | | `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[components.Intern](../../components/intern.mdx)** ### Errors | Error Type | Status Code | Content Type | | ----------------------------- | ------------------ | ---------------- | | errors.InternLifecycleError | 401, 403, 404, 408 | application/json | | errors.InternLifecycleError | 500 | application/json | | errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* | ## update\_intern Changes the intern name, description, instructions or model. Omitted fields stay unchanged. 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/client-sdks/python/docs/api-reference/authentication) required. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", api_key=os.getenv("OPENROUTER_API_KEY", ""), ) as open_router: res = open_router.interns.update_intern(intern_id="7c9e6679-7425-40de-944b-e07fc1f90ae7", description="Researches customer questions", model="openai/gpt-5.4") # Handle response print(res) ``` ### Parameters | Parameter | Type | Required | Description | Example | | -------------------------- | ------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `intern_id` | *str* | :heavy\_check\_mark: | ID of an intern visible to the authenticated API key. | 7c9e6679-7425-40de-944b-e07fc1f90ae7 | | `http_referer` | *Optional\[str]* | :heavy\_minus\_sign: | The app identifier should be your app's URL and is used as the primary identifier for rankings.
This is used to track API usage per application.
| | | `x_open_router_title` | *Optional\[str]* | :heavy\_minus\_sign: | The app display name allows you to customize how your app appears in OpenRouter's dashboard.
| | | `x_open_router_categories` | *Optional\[str]* | :heavy\_minus\_sign: | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.
| | | `description` | *OptionalNullable\[str]* | :heavy\_minus\_sign: | New free-form description. Null clears it. | | | `instructions` | *OptionalNullable\[str]* | :heavy\_minus\_sign: | New standing instructions. Null clears them. | | | `model` | *OptionalNullable\[str]* | :heavy\_minus\_sign: | New OpenRouter model slug. Null restores the workspace default. | | | `name` | *Optional\[str]* | :heavy\_minus\_sign: | New intern name, unique per creator within the workspace. | | | `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[components.Intern](../../components/intern.mdx)** ### Errors | Error Type | Status Code | Content Type | | ----------------------------- | ---------------------------- | ---------------- | | errors.InternLifecycleError | 400, 401, 403, 404, 408, 413 | application/json | | errors.InternLifecycleError | 500 | application/json | | errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* | ## provision\_intern Starts the first boot, or resumes an intern after suspension. 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/client-sdks/python/docs/api-reference/authentication) required. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", api_key=os.getenv("OPENROUTER_API_KEY", ""), ) as open_router: res = open_router.interns.provision_intern(intern_id="7c9e6679-7425-40de-944b-e07fc1f90ae7") # Handle response print(res) ``` ### Parameters | Parameter | Type | Required | Description | Example | | -------------------------- | ------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `intern_id` | *str* | :heavy\_check\_mark: | ID of an intern visible to the authenticated API key. | 7c9e6679-7425-40de-944b-e07fc1f90ae7 | | `http_referer` | *Optional\[str]* | :heavy\_minus\_sign: | The app identifier should be your app's URL and is used as the primary identifier for rankings.
This is used to track API usage per application.
| | | `x_open_router_title` | *Optional\[str]* | :heavy\_minus\_sign: | The app display name allows you to customize how your app appears in OpenRouter's dashboard.
| | | `x_open_router_categories` | *Optional\[str]* | :heavy\_minus\_sign: | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.
| | | `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[components.ProvisionInternResponse](../../components/provisioninternresponse.mdx)** ### Errors | Error Type | Status Code | Content Type | | ----------------------------- | ----------------------- | ---------------- | | errors.InternLifecycleError | 401, 403, 404, 408, 409 | application/json | | errors.InternLifecycleError | 500, 502 | application/json | | errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* | ## suspend\_intern Stops the intern runtime while keeping its disk and configuration for a later provision call. 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/client-sdks/python/docs/api-reference/authentication) required. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", api_key=os.getenv("OPENROUTER_API_KEY", ""), ) as open_router: res = open_router.interns.suspend_intern(intern_id="7c9e6679-7425-40de-944b-e07fc1f90ae7") # Handle response print(res) ``` ### Parameters | Parameter | Type | Required | Description | Example | | -------------------------- | ------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `intern_id` | *str* | :heavy\_check\_mark: | ID of an intern visible to the authenticated API key. | 7c9e6679-7425-40de-944b-e07fc1f90ae7 | | `http_referer` | *Optional\[str]* | :heavy\_minus\_sign: | The app identifier should be your app's URL and is used as the primary identifier for rankings.
This is used to track API usage per application.
| | | `x_open_router_title` | *Optional\[str]* | :heavy\_minus\_sign: | The app display name allows you to customize how your app appears in OpenRouter's dashboard.
| | | `x_open_router_categories` | *Optional\[str]* | :heavy\_minus\_sign: | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.
| | | `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[components.SuspendInternResponse](../../components/suspendinternresponse.mdx)** ### Errors | Error Type | Status Code | Content Type | | ----------------------------- | ----------------------- | ---------------- | | errors.InternLifecycleError | 401, 403, 404, 408, 409 | application/json | | errors.InternLifecycleError | 500, 502 | application/json | | errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* | ## chat Sends a prompt to one of your interns and streams the reply as OpenAI-compatible server-sent events ending with `[DONE]`. The run executes on the intern, which may pause to ask you something. It then streams one `openrouter.provide_input` tool call and finishes with `finish_reason: "tool_calls"`, and the run stays open on the intern. Every response, whether it ends with `stop`, `tool_calls` or `error`, is followed by a final chunk with empty `choices` that carries `session_id`, then `data: [DONE]`. That chunk carries the `usage` the intern reported for the run, after `stop` or `error`, and `null` when the intern reported none. After `tool_calls` its `usage` is `null` because the turn is not over. Read through `[DONE]`: the `session_id` you need to reply arrives after the `tool_calls` finish chunk. To answer, send a second request with the same `session_id`, the assistant message echoing that tool call, and a `tool` message whose `tool_call_id` is the tool call id and whose `content` is the answer. The answer is delivered to the run that asked and the stream continues from where it paused. A question stays open for its interaction deadline (5 minutes by default) and the run is cancelled when that passes. Rejected replies do not extend the deadline. Closing the connection after the `[DONE]` that follows `finish_reason: "tool_calls"` keeps the run alive. Disconnecting while a response is still streaming cancels the run. The disconnect is noticed when the intern next writes to the stream, which during a silent tool run can take more than one 30 second heartbeat interval. A run the intern ends while you are still connected, by cancellation or by a deadline, ends the stream with a `finish_reason: "error"` chunk carrying `410` and reason `run_ended`, then the final empty-`choices` chunk and `[DONE]`. That error reports only an ending the intern confirmed. A connection that breaks without that confirmation ends with reason `stream_severed`, and a client that has already disconnected is promised no final event. Set `approval_mode` to `manual` to have the intern ask before approval-bearing tools such as the shell. Omitted, the run self-drives and consents on your behalf. The mode belongs to the run started by that prompt and must be repeated on later prompts. Available to interns programme members. Callers outside the programme receive `404` for every path under `/api/v1/interns`. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", api_key=os.getenv("OPENROUTER_API_KEY", ""), ) as open_router: res = open_router.interns.chat(intern_id="a11e0000-0000-4000-8000-000000000005", messages=[ { "content": "Summarize the open pull requests.", "role": "user", }, ], approval_mode="manual") with res as event_stream: for event in event_stream: # handle event print(event, flush=True) ``` ### Parameters | Parameter | Type | Required | Description | Example | | -------------------------- | ------------------------------------------------------------------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `intern_id` | *str* | :heavy\_check\_mark: | The intern to talk to. | a11e0000-0000-4000-8000-000000000005 | | `messages` | List\[[components.InternChatMessage](../../components/internchatmessage.mdx)] | :heavy\_check\_mark: | The conversation. Only the last message is read. A last `user` message starts a run. A last `tool` message answers the interaction named by its `tool_call_id` and requires `session_id`. | | | `http_referer` | *Optional\[str]* | :heavy\_minus\_sign: | The app identifier should be your app's URL and is used as the primary identifier for rankings.
This is used to track API usage per application.
| | | `x_open_router_title` | *Optional\[str]* | :heavy\_minus\_sign: | The app display name allows you to customize how your app appears in OpenRouter's dashboard.
| | | `x_open_router_categories` | *Optional\[str]* | :heavy\_minus\_sign: | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.
| | | `approval_mode` | [Optional\[components.InternApprovalMode\]](../../components/internapprovalmode.mdx) | :heavy\_minus\_sign: | How the run started by this prompt handles tool approvals. `self-drive` (the default when omitted) consents on your behalf and runs the shell unsandboxed. `manual` asks you before an approval-bearing tool runs, as an `openrouter.provide_input` permission request, and keeps the shell sandboxed until an escalation is allowed. The mode applies to the run this prompt starts and is not remembered by the session. Repeat it on each new prompt that should use it. A `tool` reply continues the run under the mode it started with. | manual | | `model` | *Optional\[str]* | :heavy\_minus\_sign: | Echoed as `model` on the streamed chunks; the final chunk may carry the model the intern reported instead. The intern chooses its own model, so this value does not change what runs. | openrouter/intern | | `session_id` | *Optional\[str]* | :heavy\_minus\_sign: | The daemon session to continue, as returned in `session_id` on the final chunk of an earlier response. Omit it to start a new session. Required when the last message has role `tool`. | ses\_7f3c9a | | `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[operations.CreateInternChatCompletionResponse](../../operations/createinternchatcompletionresponse.mdx)** ### Errors | Error Type | Status Code | Content Type | | ------------------------------ | -------------------------------------- | ---------------- | | errors.InternChatErrorResponse | 400, 401, 403, 404, 409, 410, 413, 429 | application/json | | errors.InternChatErrorResponse | 502, 503, 504 | application/json | | errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* |