> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI Tools API

> Turn an OpenAPI spec into a typed set of AI SDK tools, one per operation.

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.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  createOpenApiTools,
  createOpenApiToolsSync,
  createOpenApiTool,
  createOpenApiToolSync,
  listOperations,
} from "smithers-orchestrator";
```

<Note>
  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.
</Note>

## createOpenApiTools

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

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
function createOpenApiTools(
  input: string | OpenApiSpec,
  options?: OpenApiToolsOptions,
): Promise<Record<string, Tool>>;
```

<ParamField path="input" type="string | OpenApiSpec" required>
  The spec as a parsed object, a file path, an HTTP URL, or raw JSON/YAML text.
</ParamField>

<ParamField path="options" type="OpenApiToolsOptions">
  Auth, filtering, base URL, and per-operation curation.

  <Expandable title="OpenApiToolsOptions">
    <ParamField path="baseUrl" type="string">
      Override the request base URL. Defaults to the spec's first
      `servers[].url`.
    </ParamField>

    <ParamField path="headers" type="Record<string, string>">
      Static headers merged into every request.
    </ParamField>

    <ParamField path="auth" type="OpenApiAuth">
      Authentication applied to every request. See [Types](#types).
    </ParamField>

    <ParamField path="include" type="string[]">
      Allowlist of `operationId`s; only listed operations become tools.
    </ParamField>

    <ParamField path="exclude" type="string[]">
      Blocklist of `operationId`s. If both `include` and `exclude` are set,
      `exclude` wins.
    </ParamField>

    <ParamField path="namePrefix" type="string">
      Prefix added to generated tool names. Does not change the `operationId`
      used for filtering.
    </ParamField>

    <ParamField path="operations" type="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.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="Promise<Record<string, Tool>>" type="object">
  A record of AI SDK tools keyed by `operationId` (or the curated `name`).
</ResponseField>

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { ToolLoopAgent } from "ai";
import { openai } from "@ai-sdk/openai";
import { createOpenApiTools } from "smithers-orchestrator";

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`](https://github.com/smithersai/smithers/blob/main/packages/openapi/src/tool-factory/createOpenApiTools.js) · [`OpenApiToolsOptions.ts`](https://github.com/smithersai/smithers/blob/main/packages/openapi/src/OpenApiToolsOptions.ts) · **Tests** [`tool-factory.test.js`](https://github.com/smithersai/smithers/blob/main/packages/openapi/tests/tool-factory.test.js) · **See also** [OpenAPI tools](/concepts/openapi-tools), [Tools](/integrations/tools)

## createOpenApiToolsSync

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

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
function createOpenApiToolsSync(
  input: string | OpenApiSpec,
  options?: OpenApiToolsOptions,
): Record<string, Tool>;
```

<ParamField path="input" type="string | OpenApiSpec" required>
  A parsed spec object, a local file path, or raw JSON/YAML text. URLs are not
  fetched.
</ParamField>

<ParamField path="options" type="OpenApiToolsOptions">
  Identical to [`createOpenApiTools`](#createopenapitools).
</ParamField>

<ResponseField name="Record<string, Tool>" type="object">
  A record of AI SDK tools keyed by `operationId`.
</ResponseField>

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const tools = createOpenApiToolsSync("./petstore.json", {
  exclude: ["deletePet"],
});
```

**Source** [`createOpenApiToolsSync.js`](https://github.com/smithersai/smithers/blob/main/packages/openapi/src/tool-factory/createOpenApiToolsSync.js) · **Tests** [`tool-factory.test.js`](https://github.com/smithersai/smithers/blob/main/packages/openapi/tests/tool-factory.test.js) · **See also** [OpenAPI tools](/concepts/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.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
function createOpenApiTool(
  input: string | OpenApiSpec,
  operationId: string,
  options?: OpenApiToolsOptions,
): Promise<Tool>;

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

<ParamField path="input" type="string | OpenApiSpec" required>
  The spec. `createOpenApiTool` accepts a URL; `createOpenApiToolSync` does not.
</ParamField>

<ParamField path="operationId" type="string" required>
  The `operationId` of the operation to turn into a tool.
</ParamField>

<ParamField path="options" type="OpenApiToolsOptions">
  Same shape as [`createOpenApiTools`](#createopenapitools). `include` /
  `exclude` are ignored here since one operation is named directly.
</ParamField>

<ResponseField name="Tool" type="object">
  A single AI SDK tool. `createOpenApiTool` returns a `Promise<Tool>`.
</ResponseField>

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

**Source** [`createOpenApiTool.js`](https://github.com/smithersai/smithers/blob/main/packages/openapi/src/tool-factory/createOpenApiTool.js) · [`createOpenApiToolSync.js`](https://github.com/smithersai/smithers/blob/main/packages/openapi/src/tool-factory/createOpenApiToolSync.js) · **Tests** [`tool-factory.test.js`](https://github.com/smithersai/smithers/blob/main/packages/openapi/tests/tool-factory.test.js) · **See also** [Tools](/integrations/tools)

## listOperations

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

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
function listOperations(input: string | OpenApiSpec): Array<{
  operationId: string;
  method: string;
  path: string;
  summary: string;
}>;
```

<ParamField path="input" type="string | OpenApiSpec" required>
  A parsed spec object, a local file path, or raw JSON/YAML text.
</ParamField>

<ResponseField name="Array<OperationSummary>" type="array">
  One entry per operation.

  <Expandable title="OperationSummary">
    <ResponseField name="operationId" type="string">
      The operation's `operationId`, the key tools are generated under.
    </ResponseField>

    <ResponseField name="method" type="string">
      HTTP method (`get`, `post`, `put`, `delete`, `patch`).
    </ResponseField>

    <ResponseField name="path" type="string">
      The path template, e.g. `/pets/{id}`.
    </ResponseField>

    <ResponseField name="summary" type="string">
      The operation's `summary`, or an empty string when absent.
    </ResponseField>
  </Expandable>
</ResponseField>

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
for (const op of listOperations("./petstore.json")) {
  console.log(`${op.method.toUpperCase()} ${op.path} → ${op.operationId}`);
}
```

The same preview is available from the CLI:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bunx smithers-orchestrator openapi list ./api/openapi.yaml
```

**Source** [`listOperations.js`](https://github.com/smithersai/smithers/blob/main/packages/openapi/src/tool-factory/listOperations.js) · **Tests** [`spec-parser.test.js`](https://github.com/smithersai/smithers/blob/main/packages/openapi/tests/spec-parser.test.js) · **See also** [OpenAPI tools](/concepts/openapi-tools)

## Types

`OpenApiAuth`, `OpenApiSpec`, and `OpenApiToolsOptions` are exported from
`smithers-orchestrator`. `Tool` is the AI SDK tool type from the `ai` package.

### OpenApiAuth

Applied to every request. A discriminated union on `type`.

<ResponseField name="OpenApiAuth" type="union">
  <Expandable title="type: &#x22;apiKey&#x22;">
    <ResponseField name="name" type="string" required>
      Header or query-parameter name carrying the key.
    </ResponseField>

    <ResponseField name="value" type="string" required>
      The API key value.
    </ResponseField>

    <ResponseField name="in" type="&#x22;header&#x22; | &#x22;query&#x22;" required>
      Where to place the key.
    </ResponseField>
  </Expandable>

  <Expandable title="type: &#x22;bearer&#x22;">
    <ResponseField name="token" type="string" required>
      Sent as `Authorization: Bearer <token>`.
    </ResponseField>
  </Expandable>

  <Expandable title="type: &#x22;basic&#x22;">
    <ResponseField name="username" type="string" required>
      Basic-auth username.
    </ResponseField>

    <ResponseField name="password" type="string" required>
      Basic-auth password.
    </ResponseField>
  </Expandable>
</ResponseField>

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import type { OpenApiAuth } from "smithers-orchestrator";

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.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import type { OpenApiSpec } from "smithers-orchestrator";

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](/reference/types) for the full `OpenApiSpec`,
`OpenApiPathItem`, and `OpenApiSchemaObject` shapes.

**Source** [`OpenApiAuth.ts`](https://github.com/smithersai/smithers/blob/main/packages/openapi/src/OpenApiAuth.ts) · [`OpenApiSpec.ts`](https://github.com/smithersai/smithers/blob/main/packages/openapi/src/OpenApiSpec.ts) · **Tests** [`spec-parser.test.js`](https://github.com/smithersai/smithers/blob/main/packages/openapi/tests/spec-parser.test.js) · **See also** [Types](/reference/types), [OpenAPI tools](/concepts/openapi-tools)

***

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