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

* [ListInterns](#listinterns) - List interns
* [CreateIntern](#createintern) - Create an intern
* [DeleteIntern](#deleteintern) - Delete an intern
* [GetIntern](#getintern) - Get an intern
* [UpdateIntern](#updateintern) - Update an intern
* [ProvisionIntern](#provisionintern) - Provision an intern
* [SuspendIntern](#suspendintern) - Suspend an intern
* [Chat](#chat) - Stream a chat completion with an intern

## ListInterns

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

### Example Usage

```go theme={null}
package main

import(
	"context"
	"os"
	openrouter "github.com/OpenRouterTeam/go-sdk"
	"log"
)

func main() {
    ctx := context.Background()

    s := openrouter.New(
        openrouter.WithSecurity(os.Getenv("OPENROUTER_API_KEY")),
    )

    res, err := s.Interns.ListInterns(ctx, nil, nil, nil)
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        // handle response
    }
}
```

### Parameters

| Parameter     | Type                                                       | Required             | Description                                                                 | Example                                 |
| ------------- | ---------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------- | --------------------------------------- |
| `ctx`         | [context.Context](https://pkg.go.dev/context#Context)      | :heavy\_check\_mark: | The context to use for the request.                                         |                                         |
| `limit`       | `*int64`                                                   | :heavy\_minus\_sign: | Maximum number of interns to return, from 1 through 500.                    | 50                                      |
| `status`      | \[][operations.Status](../../models/operations/status.mdx) | :heavy\_minus\_sign: | Comma-separated lifecycle statuses to include.                              | \[<br />"queued",<br />"running"<br />] |
| `workspaceID` | `*string`                                                  | :heavy\_minus\_sign: | Only return interns in this workspace. It must match the API key workspace. | 89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb    |
| `opts`        | \[][operations.Option](../../models/operations/option.mdx) | :heavy\_minus\_sign: | The options for this request.                                               |                                         |

### Response

**[\*components.InternListResponse](../../models/components/internlistresponse.mdx), error**

### Errors

| Error Type                     | Status Code             | Content Type     |
| ------------------------------ | ----------------------- | ---------------- |
| sdkerrors.InternLifecycleError | 400, 401, 403, 404, 408 | application/json |
| sdkerrors.InternLifecycleError | 500                     | application/json |
| sdkerrors.APIError             | 4XX, 5XX                | \*/\*            |

## CreateIntern

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

### Example Usage

```go theme={null}
package main

import(
	"context"
	"os"
	openrouter "github.com/OpenRouterTeam/go-sdk"
	"github.com/OpenRouterTeam/go-sdk/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := openrouter.New(
        openrouter.WithSecurity(os.Getenv("OPENROUTER_API_KEY")),
    )

    res, err := s.Interns.CreateIntern(ctx, components.CreateInternRequest{
        Name: "research-assistant",
        Provision: openrouter.Pointer(true),
        WorkspaceID: "89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb",
    }, nil)
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        // handle response
    }
}
```

### Parameters

| Parameter             | Type                                                                              | Required             | Description                                                                                                                  | Example                                                                                                                           |
| --------------------- | --------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `ctx`                 | [context.Context](https://pkg.go.dev/context#Context)                             | :heavy\_check\_mark: | The context to use for the request.                                                                                          |                                                                                                                                   |
| `createInternRequest` | [components.CreateInternRequest](../../models/components/createinternrequest.mdx) | :heavy\_check\_mark: | N/A                                                                                                                          | \{<br />"name": "research-assistant",<br />"provision": true,<br />"workspace\_id": "89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb"<br />} |
| `idempotencyKey`      | `*string`                                                                         | :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                                                                                              |
| `opts`                | \[][operations.Option](../../models/operations/option.mdx)                        | :heavy\_minus\_sign: | The options for this request.                                                                                                |                                                                                                                                   |

### Response

**[\*components.Intern](../../models/components/intern.mdx), error**

### Errors

| Error Type                     | Status Code                       | Content Type     |
| ------------------------------ | --------------------------------- | ---------------- |
| sdkerrors.InternLifecycleError | 400, 401, 403, 404, 408, 409, 413 | application/json |
| sdkerrors.InternLifecycleError | 500, 502                          | application/json |
| sdkerrors.APIError             | 4XX, 5XX                          | \*/\*            |

## DeleteIntern

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

### Example Usage

```go theme={null}
package main

import(
	"context"
	"os"
	openrouter "github.com/OpenRouterTeam/go-sdk"
	"log"
)

func main() {
    ctx := context.Background()

    s := openrouter.New(
        openrouter.WithSecurity(os.Getenv("OPENROUTER_API_KEY")),
    )

    res, err := s.Interns.DeleteIntern(ctx, "7c9e6679-7425-40de-944b-e07fc1f90ae7")
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        // handle response
    }
}
```

### Parameters

| Parameter  | Type                                                       | Required             | Description                                           | Example                              |
| ---------- | ---------------------------------------------------------- | -------------------- | ----------------------------------------------------- | ------------------------------------ |
| `ctx`      | [context.Context](https://pkg.go.dev/context#Context)      | :heavy\_check\_mark: | The context to use for the request.                   |                                      |
| `internID` | `string`                                                   | :heavy\_check\_mark: | ID of an intern visible to the authenticated API key. | 7c9e6679-7425-40de-944b-e07fc1f90ae7 |
| `opts`     | \[][operations.Option](../../models/operations/option.mdx) | :heavy\_minus\_sign: | The options for this request.                         |                                      |

### Response

**[\*components.DeleteInternResponse](../../models/components/deleteinternresponse.mdx), error**

### Errors

| Error Type                     | Status Code             | Content Type     |
| ------------------------------ | ----------------------- | ---------------- |
| sdkerrors.InternLifecycleError | 401, 403, 404, 408, 409 | application/json |
| sdkerrors.InternLifecycleError | 500, 502                | application/json |
| sdkerrors.APIError             | 4XX, 5XX                | \*/\*            |

## GetIntern

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

### Example Usage

```go theme={null}
package main

import(
	"context"
	"os"
	openrouter "github.com/OpenRouterTeam/go-sdk"
	"log"
)

func main() {
    ctx := context.Background()

    s := openrouter.New(
        openrouter.WithSecurity(os.Getenv("OPENROUTER_API_KEY")),
    )

    res, err := s.Interns.GetIntern(ctx, "7c9e6679-7425-40de-944b-e07fc1f90ae7")
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        // handle response
    }
}
```

### Parameters

| Parameter  | Type                                                       | Required             | Description                                           | Example                              |
| ---------- | ---------------------------------------------------------- | -------------------- | ----------------------------------------------------- | ------------------------------------ |
| `ctx`      | [context.Context](https://pkg.go.dev/context#Context)      | :heavy\_check\_mark: | The context to use for the request.                   |                                      |
| `internID` | `string`                                                   | :heavy\_check\_mark: | ID of an intern visible to the authenticated API key. | 7c9e6679-7425-40de-944b-e07fc1f90ae7 |
| `opts`     | \[][operations.Option](../../models/operations/option.mdx) | :heavy\_minus\_sign: | The options for this request.                         |                                      |

### Response

**[\*components.Intern](../../models/components/intern.mdx), error**

### Errors

| Error Type                     | Status Code        | Content Type     |
| ------------------------------ | ------------------ | ---------------- |
| sdkerrors.InternLifecycleError | 401, 403, 404, 408 | application/json |
| sdkerrors.InternLifecycleError | 500                | application/json |
| sdkerrors.APIError             | 4XX, 5XX           | \*/\*            |

## UpdateIntern

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

### Example Usage

```go theme={null}
package main

import(
	"context"
	"os"
	openrouter "github.com/OpenRouterTeam/go-sdk"
	"github.com/OpenRouterTeam/go-sdk/optionalnullable"
	"github.com/OpenRouterTeam/go-sdk/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := openrouter.New(
        openrouter.WithSecurity(os.Getenv("OPENROUTER_API_KEY")),
    )

    res, err := s.Interns.UpdateIntern(ctx, "7c9e6679-7425-40de-944b-e07fc1f90ae7", components.UpdateInternRequest{
        Description: optionalnullable.From(openrouter.Pointer("Researches customer questions")),
        Model: optionalnullable.From(openrouter.Pointer("openai/gpt-5.4")),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        // handle response
    }
}
```

### Parameters

| Parameter             | Type                                                                              | Required             | Description                                           | Example                                                                                       |
| --------------------- | --------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `ctx`                 | [context.Context](https://pkg.go.dev/context#Context)                             | :heavy\_check\_mark: | The context to use for the request.                   |                                                                                               |
| `internID`            | `string`                                                                          | :heavy\_check\_mark: | ID of an intern visible to the authenticated API key. | 7c9e6679-7425-40de-944b-e07fc1f90ae7                                                          |
| `updateInternRequest` | [components.UpdateInternRequest](../../models/components/updateinternrequest.mdx) | :heavy\_check\_mark: | N/A                                                   | \{<br />"description": "Researches customer questions",<br />"model": "openai/gpt-5.4"<br />} |
| `opts`                | \[][operations.Option](../../models/operations/option.mdx)                        | :heavy\_minus\_sign: | The options for this request.                         |                                                                                               |

### Response

**[\*components.Intern](../../models/components/intern.mdx), error**

### Errors

| Error Type                     | Status Code                  | Content Type     |
| ------------------------------ | ---------------------------- | ---------------- |
| sdkerrors.InternLifecycleError | 400, 401, 403, 404, 408, 413 | application/json |
| sdkerrors.InternLifecycleError | 500                          | application/json |
| sdkerrors.APIError             | 4XX, 5XX                     | \*/\*            |

## ProvisionIntern

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

### Example Usage

```go theme={null}
package main

import(
	"context"
	"os"
	openrouter "github.com/OpenRouterTeam/go-sdk"
	"log"
)

func main() {
    ctx := context.Background()

    s := openrouter.New(
        openrouter.WithSecurity(os.Getenv("OPENROUTER_API_KEY")),
    )

    res, err := s.Interns.ProvisionIntern(ctx, "7c9e6679-7425-40de-944b-e07fc1f90ae7")
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        // handle response
    }
}
```

### Parameters

| Parameter  | Type                                                       | Required             | Description                                           | Example                              |
| ---------- | ---------------------------------------------------------- | -------------------- | ----------------------------------------------------- | ------------------------------------ |
| `ctx`      | [context.Context](https://pkg.go.dev/context#Context)      | :heavy\_check\_mark: | The context to use for the request.                   |                                      |
| `internID` | `string`                                                   | :heavy\_check\_mark: | ID of an intern visible to the authenticated API key. | 7c9e6679-7425-40de-944b-e07fc1f90ae7 |
| `opts`     | \[][operations.Option](../../models/operations/option.mdx) | :heavy\_minus\_sign: | The options for this request.                         |                                      |

### Response

**[\*components.ProvisionInternResponse](../../models/components/provisioninternresponse.mdx), error**

### Errors

| Error Type                     | Status Code             | Content Type     |
| ------------------------------ | ----------------------- | ---------------- |
| sdkerrors.InternLifecycleError | 401, 403, 404, 408, 409 | application/json |
| sdkerrors.InternLifecycleError | 500, 502                | application/json |
| sdkerrors.APIError             | 4XX, 5XX                | \*/\*            |

## SuspendIntern

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

### Example Usage

```go theme={null}
package main

import(
	"context"
	"os"
	openrouter "github.com/OpenRouterTeam/go-sdk"
	"log"
)

func main() {
    ctx := context.Background()

    s := openrouter.New(
        openrouter.WithSecurity(os.Getenv("OPENROUTER_API_KEY")),
    )

    res, err := s.Interns.SuspendIntern(ctx, "7c9e6679-7425-40de-944b-e07fc1f90ae7")
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        // handle response
    }
}
```

### Parameters

| Parameter  | Type                                                       | Required             | Description                                           | Example                              |
| ---------- | ---------------------------------------------------------- | -------------------- | ----------------------------------------------------- | ------------------------------------ |
| `ctx`      | [context.Context](https://pkg.go.dev/context#Context)      | :heavy\_check\_mark: | The context to use for the request.                   |                                      |
| `internID` | `string`                                                   | :heavy\_check\_mark: | ID of an intern visible to the authenticated API key. | 7c9e6679-7425-40de-944b-e07fc1f90ae7 |
| `opts`     | \[][operations.Option](../../models/operations/option.mdx) | :heavy\_minus\_sign: | The options for this request.                         |                                      |

### Response

**[\*components.SuspendInternResponse](../../models/components/suspendinternresponse.mdx), error**

### Errors

| Error Type                     | Status Code             | Content Type     |
| ------------------------------ | ----------------------- | ---------------- |
| sdkerrors.InternLifecycleError | 401, 403, 404, 408, 409 | application/json |
| sdkerrors.InternLifecycleError | 500, 502                | application/json |
| sdkerrors.APIError             | 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

```go theme={null}
package main

import(
	"context"
	"os"
	openrouter "github.com/OpenRouterTeam/go-sdk"
	"github.com/OpenRouterTeam/go-sdk/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := openrouter.New(
        openrouter.WithSecurity(os.Getenv("OPENROUTER_API_KEY")),
    )

    res, err := s.Interns.Chat(ctx, "a11e0000-0000-4000-8000-000000000005", components.InternChatCompletionRequest{
        ApprovalMode: components.InternApprovalModeManual.ToPointer(),
        Messages: []components.InternChatMessage{
            components.CreateInternChatMessageUser(
                components.InternChatUserMessage{
                    Content: openrouter.Pointer(components.CreateInternChatMessageContentStr(
                        "Summarize the open pull requests.",
                    )),
                    Role: components.InternChatUserMessageRoleUser,
                },
            ),
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        defer res.InternChatStreamingResponse.Close()

        for res.InternChatStreamingResponse.Next() {
            event := res.InternChatStreamingResponse.Value()
            log.Print(event)
            // Handle the event
	      }
    }
}
```

### Parameters

| Parameter                     | Type                                                                                              | Required             | Description                         | Example                                                                                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ctx`                         | [context.Context](https://pkg.go.dev/context#Context)                                             | :heavy\_check\_mark: | The context to use for the request. |                                                                                                                                                                                    |
| `internID`                    | `string`                                                                                          | :heavy\_check\_mark: | The intern to talk to.              | a11e0000-0000-4000-8000-000000000005                                                                                                                                               |
| `internChatCompletionRequest` | [components.InternChatCompletionRequest](../../models/components/internchatcompletionrequest.mdx) | :heavy\_check\_mark: | N/A                                 | \{<br />"approval\_mode": "manual",<br />"messages": \[<br />\{<br />"content": "Summarize the open pull requests.",<br />"role": "user"<br />}<br />],<br />"stream": true<br />} |
| `opts`                        | \[][operations.Option](../../models/operations/option.mdx)                                        | :heavy\_minus\_sign: | The options for this request.       |                                                                                                                                                                                    |

### Response

**[\*stream.EventStream\[components.InternChatStreamingResponse\]](../../.mdx), error**

### Errors

| Error Type                        | Status Code                            | Content Type     |
| --------------------------------- | -------------------------------------- | ---------------- |
| sdkerrors.InternChatErrorResponse | 400, 401, 403, 404, 409, 410, 413, 429 | application/json |
| sdkerrors.InternChatErrorResponse | 502, 503, 504                          | application/json |
| sdkerrors.APIError                | 4XX, 5XX                               | \*/\*            |