Interns - OpenRouter | Documentation

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.

Available Operations

ListInterns - List interns
CreateIntern - Create an intern
DeleteIntern - Delete an intern
GetIntern - Get an intern
UpdateIntern - Update an intern
ProvisionIntern - Provision an intern
SuspendIntern - Suspend an intern
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 required.

Example Usage

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	: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	:heavy_minus_sign:	Comma-separated lifecycle statuses to include.	[ “queued”, “running” ]
`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	:heavy_minus_sign:	The options for this request.

Response

*components.InternListResponse, 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 required.

Example Usage

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	:heavy_check_mark:	The context to use for the request.
`createInternRequest`	components.CreateInternRequest	:heavy_check_mark:	N/A	{ “name”: “research-assistant”, “provision”: true, “workspace_id”: “89f9f5b2-3f89-4eaf-83ca-5ceae149e8bb” }
`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	:heavy_minus_sign:	The options for this request.

Response

*components.Intern, 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 required.

Example Usage

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	: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	:heavy_minus_sign:	The options for this request.

Response

*components.DeleteInternResponse, 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 required.

Example Usage

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	: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	:heavy_minus_sign:	The options for this request.

Response

*components.Intern, 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 required.

Example Usage

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	: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	:heavy_check_mark:	N/A	{ “description”: “Researches customer questions”, “model”: “openai/gpt-5.4” }
`opts`	[]operations.Option	:heavy_minus_sign:	The options for this request.

Response

*components.Intern, 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 required.

Example Usage

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	: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	:heavy_minus_sign:	The options for this request.

Response

*components.ProvisionInternResponse, 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 required.

Example Usage

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	: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	:heavy_minus_sign:	The options for this request.

Response

*components.SuspendInternResponse, 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

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	: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	:heavy_check_mark:	N/A	{ “approval_mode”: “manual”, “messages”: [ { “content”: “Summarize the open pull requests.”, “role”: “user” } ], “stream”: true }
`opts`	[]operations.Option	:heavy_minus_sign:	The options for this request.

Response

*stream.EventStream[components.InternChatStreamingResponse], 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	/

​Overview

​Available Operations

​ListInterns

​Example Usage

​Parameters

​Response

​Errors

​CreateIntern

​Example Usage

​Parameters

​Response

​Errors

​DeleteIntern

​Example Usage

​Parameters

​Response

​Errors

​GetIntern

​Example Usage

​Parameters

​Response

​Errors

​UpdateIntern

​Example Usage

​Parameters

​Response

​Errors

​ProvisionIntern

​Example Usage

​Parameters

​Response

​Errors

​SuspendIntern

​Example Usage

​Parameters

​Response

​Errors

​Chat

​Example Usage

​Parameters

​Response

​Errors

Overview

Available Operations

ListInterns

Example Usage

Parameters

Response

Errors

CreateIntern

Example Usage

Parameters

Response

Errors

DeleteIntern

Example Usage

Parameters

Response

Errors

GetIntern

Example Usage

Parameters

Response

Errors

UpdateIntern

Example Usage

Parameters

Response

Errors

ProvisionIntern

Example Usage

Parameters

Response

Errors

SuspendIntern

Example Usage

Parameters

Response

Errors

Chat

Example Usage

Parameters

Response

Errors