Quickstart | Apiweld

Go from an empty repo to a committed, typed Stripe refund client, from the terminal or through your coding agent.

This guide adds a typed client for two Stripe endpoints: create a refund and retrieve a refund. The steps are the same for any API with an OpenAPI spec.

You need Node.js 20 or newer. Install Apiweld as a dev dependency. The CLI and the MCP server are the same package.

npm i -D apiweld

yarn add -D apiweld

pnpm add -D apiweld

bun add -d apiweld

Add your first client

Create the config

npx apiweld init --agents

This writes apiweld.config.ts and adds .apiweld/ (local reports and logs) to .gitignore. --agents also adds a short section to both AGENTS.md and CLAUDE.md, creating them if needed. It tells your agent to use Apiweld instead of writing HTTP calls by hand and includes an MCP config snippet.

Generated clients go in src/apis/ by default. In a monorepo, init lists your workspace packages and asks where they should go. Press Enter to keep the default, or pass --output:

npx apiweld init --output packages/web/src/apis

The config is written to the directory you run init in. To keep it next to one app in a monorepo, run init from that app’s folder.

Add the API to your catalog

Search runs against a local catalog. Add the providers your project uses by pointing Apiweld at their OpenAPI spec:

npx apiweld catalog add stripe https://github.com/stripe/openapi/blob/master/latest/openapi.spec3.json

GitHub blob links are fine. Apiweld fetches the raw file. To index the whole APIs.guru directory up front, run catalog sync to download a prebuilt snapshot, or catalog build to index it yourself (slow).

Find the endpoints

Search by what you want to do. --ops searches endpoints instead of APIs.

npx apiweld search "refund a payment" --ops

show prints an endpoint as a short TypeScript signature, which is easier to read than raw OpenAPI:

npx apiweld show stripe PostRefunds

Generate the client

Pass the endpoints you want, either as operation ids or as METHOD /path. These two commands do the same thing:

npx apiweld add stripe PostRefunds GetRefundsRefund
npx apiweld add stripe "POST /v1/refunds" "GET /v1/refunds/{refund}"

You now have three changes to commit:

apiweld.config.ts lists the two endpoints under stripe.
src/apis/stripe/ contains the generated client.
apiweld.lock.json pins the exact spec it was built from.

The key (stripe) is the folder name and the name you import from. Pass --as to choose a different one.

Call it

The client exports one function per endpoint, named after the operation id, plus the request and response types.

import { client } from "./apis/stripe/client.gen";
import { postRefunds } from "./apis/stripe";

client.setConfig({
  headers: { Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}` },
});

const { data: refund, error } = await postRefunds({
  body: { payment_intent: "pi_123", reason: "requested_by_customer" },
});

Your API keys stay in your environment. Apiweld never sees them.

Let your agent do it

claude mcp add apiweld -- npx apiweld mcp

For Cursor and other clients, see MCP tools. After that, you can ask for what you need (“refund a Stripe payment when an order is cancelled”) and the agent searches, adds the endpoints, and writes the call. Each tool matches a command from this guide, so you can re-run anything the agent did yourself.

Keep it up to date

Run check whenever you like, or on a schedule in CI. It only reports changes to the endpoints in your config.

npx apiweld check

To rebuild the client from the lock without touching the network, for example in CI to confirm the committed files match, run:

npx apiweld generate
npx apiweld verify

verify type-checks the project with its own tsconfig.json, then runs your test command if you configured one.

Next: how drift is classified, or the full CLI reference.