OpenRouter TypeScript SDK

The SCIM management endpoints allow for the management of SCIM group-to-workspace mappings. These endpoints are authenticated using a management key.

Important Distinction: These are not the SCIM 2.0 connector endpoints used by your identity provider. When configuring provisioning in your identity provider, you should use the specific SCIM endpoint URL provided in the OpenRouter dashboard under Settings > Members > SCIM Mappings.

The OpenRouter Datasets API provides access to public usage datasets. This data is licensed under CC BY 4.0, allowing for reuse and republication (including commercially) provided that attribution is given to OpenRouter.

Available Operations

• getAppRankings: Returns top public apps ranked by token usage.
• getRankingsDaily: Returns daily token totals for the top 50 models.
• getSessionCost: Returns cost per session by harness and model.

Usage Constraints & Requirements

• Authentication: Use any valid OpenRouter API key (the same key used for inference).
• Rate Limits: 30 requests/minute per key and 500 requests/day per account.
• Attribution: When quoting or republishing, use the format: "Source: OpenRouter (openrouter.ai/apps), as of {as_of}."

The Generations API provides endpoints to manage and inspect generation history:

• getGeneration: Get request & usage metadata for a generation.
• listGenerationContent: Get stored prompt, completion, and error content for a generation.
• submitFeedback: Submit feedback for a generation.

OpenRouter Interns can be managed (created, inspected, updated, provisioned, suspended, or deleted) through the SDK using an API key. Additionally, you can interact with them via a chat route that streams OpenAI-compatible completions. When an intern requires permission or an answer, the stream will pause and issue an openrouter.provide_input tool call.

Note: These features are only available to members of the interns programme; other callers will receive a 404 error. Requests made to regional hostnames (e.g., eu.openrouter.ai) will be refused.

The Vault service allows you to store host-bound secrets for either a workspace or a specific intern. The scope of the operation (workspace vs. intern) is determined by the provided API key.

Important Security Note: Responses from Vault API calls return metadata only (such as names, bound hosts, fingerprints, and creation times). The actual secret values are never returned by the API.

Requirements & Constraints:

• Every Vault route requires access to the Intern API programme; otherwise, it returns a 404.
• Requests made to regional hostnames (e.g., eu.openrouter.ai) will be refused.
• There is no default workspace; the API key must explicitly target a scope.

The ContainerReferenceEnvironment model allows you to reference a container using its canonical ID (a previously returned container_id) or a fresh name to create a persistent container. This is used when you want to interact with an existing container session rather than starting a new one.

import { ContainerReferenceEnvironment } from "@openrouter/sdk/models";

let value: ContainerReferenceEnvironment = {
  containerId: "sess_abc123",
  type: "container_reference",
};

When working with multiple subagents, the instanceName field is used to distinguish between them.

• Default Instance: The first subagent entry in the request tools array is the default instance and will not include an instanceName.
• Non-default Instances: The second and subsequent subagent entries in the tools array will include a provider-safe name (e.g., openrouter_subagent__1).
• Positional Identity: The instanceName is derived from the index of the subagent in the tools array. To ensure correct transcript rehydration during replays, you must keep the order of subagent entries stable across all requests in a conversation.

The ScimSyncJob model represents the state and metadata of a SCIM (System for Cross-domain Identity Management) synchronization task. It provides details about when a job started and finished, its current execution status, and the outcome of the synchronization (such as the number of groups synced or deleted).

import { ScimSyncJob } from "@openrouter/sdk/models";

let value: ScimSyncJob = {
  createdAt: "1717120563145",
  deletedGroups: null,
  errorMessage: "<value>",
  finishedAt: "<value>",
  id: "15580601-fb00-4868-a8e7-1e1a16bb7a7f",
  startedAt: "<value>",
  status: "succeeded",
  syncedGroups: null,
};

The GenerationContentData type represents the stored content of a model generation, including the original prompt (input), the resulting completion (output), and any error information if the generation failed. It is used to track the lifecycle and results of a single generation request.

import { GenerationContentData } from "@openrouter/sdk/models";

let value: GenerationContentData = {
  error: null,
  input: {
    messages: [
      {
        "content": "What is the meaning of life?",
        "role": "user",
      },
    ],
  },
  output: {
    completion: "The meaning of life is a philosophical question...",
    reasoning: null,
  },
};

The ProviderPreferences type allows you to specify how OpenRouter should route your requests to different model providers. You can use this to influence which specific providers are used for a given model request.

import { ProviderPreferences } from "@openrouter/sdk/models";

let value: ProviderPreferences = {};