---
title: OpenAPI Tools Quickstart
description: Load an OpenAPI spec, create tools, and give them to an agent in under five minutes.
---

## Prerequisites

You need a Smithers project and an OpenAPI 3.0+ spec. The spec can be a JSON file, a YAML file, a URL, or a plain JavaScript object.

## Install

No extra dependencies. OpenAPI tools are built into `smithers-orchestrator`.

## Load a Spec and Create Tools

```ts
import { createOpenApiTools } from "smithers-orchestrator";

const tools = await createOpenApiTools("./petstore.json", {
  baseUrl: "https://api.petstore.example.com",
  auth: { type: "bearer", token: process.env.PETSTORE_TOKEN! },
});

console.log(Object.keys(tools));
// ["listPets", "createPet", "getPet"]
```

Each key is the `operationId` from the spec. Each value is an AI SDK `tool()`.

## Use Tools in a Workflow

```tsx
import { Workflow, Task, AnthropicAgent } from "smithers-orchestrator";
import { createOpenApiTools } from "smithers-orchestrator";

const petTools = await createOpenApiTools("./petstore.json", {
  baseUrl: "https://api.petstore.example.com",
  auth: { type: "bearer", token: process.env.PETSTORE_TOKEN! },
});

const agent = new AnthropicAgent({
  model: "claude-sonnet-4-20250514",
  tools: petTools,
});

export default (
  <Workflow>
    <Task id="list-pets" agent={agent}>
      List all available pets and summarize them.
    </Task>
  </Workflow>
);
```

## Filter Operations

```ts
// Only expose read operations
const readTools = await createOpenApiTools("./petstore.json", {
  include: ["listPets", "getPet"],
});

// Expose everything except destructive operations
const safeTools = await createOpenApiTools("./petstore.json", {
  exclude: ["deletePet"],
});
```

## Single Tool

```ts
import { createOpenApiTool } from "smithers-orchestrator";

const listPets = await createOpenApiTool("./petstore.json", "listPets", {
  baseUrl: "https://api.petstore.example.com",
});
```

## Preview Tools from CLI

```bash
smithers openapi list ./petstore.json
```

Output:

```
  listPets — List all pets
  createPet — Create a pet
  getPet — Get a pet by ID

  3 tool(s) from spec
```

## Authentication Options

```ts
// Bearer token
await createOpenApiTools(spec, {
  auth: { type: "bearer", token: "sk-..." },
});

// Basic auth
await createOpenApiTools(spec, {
  auth: { type: "basic", username: "admin", password: "secret" },
});

// API key in header
await createOpenApiTools(spec, {
  auth: { type: "apiKey", name: "X-API-Key", value: "key123", in: "header" },
});

// API key in query string
await createOpenApiTools(spec, {
  auth: { type: "apiKey", name: "api_key", value: "key123", in: "query" },
});

// Custom headers
await createOpenApiTools(spec, {
  headers: { "X-Request-Id": "abc123" },
});
```

## Name Prefixes

When combining tools from multiple specs, use `namePrefix` to avoid collisions:

```ts
const petTools = await createOpenApiTools(petSpec, { namePrefix: "pet_" });
const orderTools = await createOpenApiTools(orderSpec, { namePrefix: "order_" });

const allTools = { ...petTools, ...orderTools };
```