Config and lockfile

Apiweld keeps a project’s state in two files, both committed:

• apiweld.config.ts says what you want: which APIs, which endpoints, and how to generate them. You (or your agent) edit it.
• apiweld.lock.json records what was actually built: the exact spec, the endpoints, and the tool versions. Apiweld writes it. Don’t edit it by hand.

This works like package.json and a package-manager lockfile. The config states intent, and the lock makes every build reproducible.

Config

import { defineConfig } from "apiweld";

export default defineConfig({
  output: "src/apis",
  generator: {
    name: "hey-api",
    client: "fetch",
    validators: "zod",
  },
  verify: {
    test: "bun run test",
  },
  apis: {
    stripe: {
      source: "https://raw.githubusercontent.com/stripe/openapi/master/latest/openapi.spec3.json",
      operations: [
        "POST /v1/refunds",
        "GET /v1/refunds/{refund}",
      ],
      policy: { autoRegenerate: "safe" },
    },
    github: {
      source: "apisguru:github.com",
      operations: ["GET /repos/{owner}/{repo}/pulls"],
    },
  },
});

The file is TypeScript, so your editor type-checks and autocompletes it, and it can hold functions such as patches. There’s no build step: Apiweld loads it directly.

After the first generate, Apiweld writes apiweld-env.d.ts, which gives you autocomplete for the operations of every API already in the lock.

Top-level options

Per-API options

Each key under apis becomes a folder under output and the name you import from.

Sources

Fix a broken spec

Some upstream specs have mistakes that break generation. Add a patch to that API to fix them. The functions go to Hey API’s parser.patch.

github: {
  source: "apisguru:github.com",
  operations: ["GET /repos/{owner}/{repo}/pulls"],
  patch: {
    schemas: {
      "pull-request-simple": (schema) => {
        // fix the schema, then return it
        return schema;
      },
    },
  },
},

Patches are code you wrote in your own config. Apiweld never runs code that comes from a spec.

How add and remove edit the file

apiweld add and remove (and the matching MCP tools) edit apiweld.config.ts in place and keep your formatting, comments, and functions. If the config is built dynamically and can’t be edited safely, Apiweld prints the snippet to paste in instead of rewriting the file.

Lockfile

{
  "lockVersion": 1,
  "apis": {
    "stripe": {
      "resolvedUrl": "https://raw.githubusercontent.com/stripe/openapi/master/latest/openapi.spec3.json",
      "specHash": "sha256:9f2c…e41a",
      "specVersion": "2026-08-27",
      "fetchedAt": "2026-09-23T07:40:12Z",
      "etag": "W/\"5d1f…\"",
      "operations": ["GET /v1/refunds/{refund}", "POST /v1/refunds"],
      "sliceHash": "sha256:1b7a…03cd",
      "schemas": 14,
      "generator": "@hey-api/openapi-ts@<version>",
      "engine": "apiweld-engine@<version> (oasdiff <version>)",
      "outputHash": "sha256:c08e…77b2"
    }
  }
}

Keys and operations are sorted, so a change to the lock always means something actually changed, not just the ordering.

The lock has three hashes, and each one answers a different question:

The other fields: resolvedUrl is the URL that was actually fetched. etag lets the next check skip the download when nothing changed. generator and engine record the tool versions, so a rebuild produces the same output.

Files in your project

apiweld.config.ts
apiweld.lock.json
apiweld-env.d.ts          # operation autocomplete for the config
src/apis/
  stripe/                 # generated: read it, don't edit it
    sdk.gen.ts
    types.gen.ts
    zod.gen.ts
    index.ts
  github/
.apiweld/                 # gitignored
  reports/                # drift reports and heal plans, JSON and Markdown
  drift.log.jsonl         # runtime drift log (shapes only, never values)

Commit the generated clients. That way reviewers see every change, agents can read the code, and CI doesn’t need the network to build.

Machine settings

Apiweld also keeps a cache that all your projects share:

~/.apiweld/
  settings.json           # optional, see below
  catalog.db              # the search index
  specs/
    9f2c…e41a.json        # every spec version fetched, named by its hash
  http-cache.json         # ETags, so unchanged specs aren't downloaded again

Old spec versions stay in specs/, so Apiweld can diff against the version in your lock and rebuild it offline even after the provider has moved on.

settings.json is optional:

{
  "offline": false,
  "proxy": "http://proxy.internal:3128",
  "catalogs": [
    { "name": "internal", "path": "/srv/specs" },
    { "name": "partners", "urls": ["https://partner.example.com/openapi.json"] }
  ]
}

catalogs adds your own specs to search, next to the public ones. Each result is labelled with the catalog it came from.