OpenAPI Tools API

Hand these factories an OpenAPI 3.x spec; get back AI SDK tools, one per operation, with Zod input schemas converted from the spec’s JSON schemas and an execute(args) that performs the HTTP call. Drop the result straight into an agent’s tools. Each operation’s summary/description becomes the tool description, so the agent already knows what each call does.

import {
  createOpenApiTools,
  createOpenApiToolsSync,
  createOpenApiTool,
  createOpenApiToolSync,
  listOperations,
} from "smthrs";

The async factories (createOpenApiTools, createOpenApiTool) fetch URL specs; the *Sync variants take only an object or a local file path and never fetch URLs. Pick async when the spec lives behind an HTTP URL.

createOpenApiTools

Build a record of tools from an entire spec, keyed by operationId.

function createOpenApiTools(
  input: string | OpenApiSpec,
  options?: OpenApiToolsOptions,
): Promise<Record<string, Tool>>;

string | OpenApiSpec

required

The spec as a parsed object, a file path, an HTTP URL, or raw JSON/YAML text.

OpenApiToolsOptions

Auth, filtering, base URL, and per-operation curation.

Show OpenApiToolsOptions

string

Override the request base URL. Defaults to the spec’s first servers[].url.

Record<string, string>

Static headers merged into every request.

OpenApiAuth

Authentication applied to every request. See Types.

string[]

Allowlist of operationIds; only listed operations become tools.

string[]

Blocklist of operationIds. If both include and exclude are set, exclude wins.

string

Prefix added to generated tool names. Does not change the operationId used for filtering.

Record<string, false | OperationCuration>

Per-operation curation keyed by the original operationId: false or { include: false } skips it, name renames the tool, description replaces the agent-facing text, and responseExamples appends concrete response shapes to it.

object

A record of AI SDK tools keyed by operationId (or the curated name).

import { ToolLoopAgent } from "ai";
import { openai } from "@ai-sdk/openai";
import { createOpenApiTools } from "smthrs";

const tools = await createOpenApiTools("https://api.example.com/openapi.json", {
  baseUrl: "https://api.example.com",
  auth: { type: "bearer", token: process.env.API_TOKEN! },
  include: ["listPets", "getPetById"],
});

const agent = new ToolLoopAgent({ model: openai("gpt-5.6-terra"), tools });

Source createOpenApiTools.js · OpenApiToolsOptions.ts · Tests tool-factory.test.js · See also OpenAPI tools, Tools

createOpenApiToolsSync

Synchronous createOpenApiTools. Use when the spec is resolvable on disk at build time.

function createOpenApiToolsSync(
  input: string | OpenApiSpec,
  options?: OpenApiToolsOptions,
): Record<string, Tool>;

string | OpenApiSpec

required

A parsed spec object, a local file path, or raw JSON/YAML text. URLs are not fetched.

OpenApiToolsOptions

Identical to createOpenApiTools.

object

A record of AI SDK tools keyed by operationId.

const tools = createOpenApiToolsSync("./petstore.json", {
  exclude: ["deletePet"],
});

Source createOpenApiToolsSync.js · Tests tool-factory.test.js · See also OpenAPI tools

createOpenApiTool / createOpenApiToolSync

Build a single tool from one operation, selected by operationId, with the same options as the bulk factories plus that one extra argument.

function createOpenApiTool(
  input: string | OpenApiSpec,
  operationId: string,
  options?: OpenApiToolsOptions,
): Promise<Tool>;

function createOpenApiToolSync(
  input: string | OpenApiSpec,
  operationId: string,
  options?: OpenApiToolsOptions,
): Tool;

string | OpenApiSpec

required

The spec. createOpenApiTool accepts a URL; createOpenApiToolSync does not.

string

required

The operationId of the operation to turn into a tool.

OpenApiToolsOptions

Same shape as createOpenApiTools. include / exclude are ignored here since one operation is named directly.

object

A single AI SDK tool. createOpenApiTool returns a Promise<Tool>.

const getPet = await createOpenApiTool("./petstore.json", "getPetById", {
  auth: { type: "apiKey", name: "X-API-Key", in: "header", value: KEY },
});

Source createOpenApiTool.js · createOpenApiToolSync.js · Tests tool-factory.test.js · See also Tools

listOperations

Introspect a spec without building tools, useful for auditing what an agent could call before wiring it up.

function listOperations(input: string | OpenApiSpec): Array<{
  operationId: string;
  method: string;
  path: string;
  summary: string;
}>;

string | OpenApiSpec

required

A parsed spec object, a local file path, or raw JSON/YAML text.

array

One entry per operation.

Show OperationSummary

string

The operation’s operationId, the key tools are generated under.

string

HTTP method (get, post, put, delete, patch).

string

The path template, e.g. /pets/{id}.

string

The operation’s summary, or an empty string when absent.

for (const op of listOperations("./petstore.json")) {
  console.log(`${op.method.toUpperCase()} ${op.path} → ${op.operationId}`);
}

The same preview is available from the CLI:

bunx smthrs openapi list ./api/openapi.yaml

Source listOperations.js · Tests spec-parser.test.js · See also OpenAPI tools

Types

OpenApiAuth, OpenApiSpec, and OpenApiToolsOptions are exported from smthrs. Tool is the AI SDK tool type from the ai package.

OpenApiAuth

Applied to every request. A discriminated union on type.

union

Show type: "apiKey"

string

required

Header or query-parameter name carrying the key.

string

required

The API key value.

"header" | "query"

required

Where to place the key.

Show type: "bearer"

string

required

Sent as Authorization: Bearer <token>.

Show type: "basic"

string

required

Basic-auth username.

string

required

Basic-auth password.

import type { OpenApiAuth } from "smthrs";

const apiKey: OpenApiAuth = { type: "apiKey", name: "X-API-Key", in: "header", value: KEY };
const bearer: OpenApiAuth = { type: "bearer", token: TOKEN };
const basic: OpenApiAuth = { type: "basic", username: USER, password: PASS };

OpenApiSpec

The parsed OpenAPI 3.x document shape accepted as object input. Most callers pass a file path or URL string and let the loader parse it; import the type only to construct or narrow a spec yourself.

import type { OpenApiSpec } from "smthrs";

type OpenApiSpec = {
  openapi: string;
  info: { title: string; version: string; description?: string };
  servers?: Array<{
    url: string;
    description?: string;
    /** `{var}` placeholders in `url` resolve from these defaults. */
    variables?: Record<string, { default: string; enum?: string[]; description?: string }>;
  }>;
  paths: Record<string, OpenApiPathItem>;
  components?: { schemas?: Record<string, OpenApiSchemaObject>; /* ... */ };
};

See the Types reference for the full OpenApiSpec, OpenApiPathItem, and OpenApiSchemaObject shapes. Source OpenApiAuth.ts · OpenApiSpec.ts · Tests spec-parser.test.js · See also Types, OpenAPI tools

For request/response handling, filtering semantics, observability metrics, and current limitations (cookie params, non-JSON bodies, Swagger 2.0), see OpenAPI tools; for wiring tools into agents, see Tools.

Overview

Core API

Runtime

Types & errors

Gateway RPC

OpenAPI Tools API

createOpenApiTools

createOpenApiToolsSync

createOpenApiTool / createOpenApiToolSync

listOperations

Types

OpenApiAuth

OpenApiSpec

​createOpenApiTools

​createOpenApiToolsSync

​createOpenApiTool / createOpenApiToolSync

​listOperations

​Types

​OpenApiAuth

​OpenApiSpec

createOpenApiTools

createOpenApiToolsSync

createOpenApiTool / createOpenApiToolSync

listOperations

Types

OpenApiAuth

OpenApiSpec