StitchAPI Docs

API stitching: turn any API into a typed, resilient function . Declare an endpoint once — its types, auth, and resilience — and call it like a local function. No server, no codegen, no config files. The same definition answers to your code, the CLI, and an AI agent alike.

📚 stitchapi.dev — documentation, guides & live playground

Zero runtime dependencies · ~21 kB min+gzip — a typical import { stitch } tree-shakes to ~19 kB, and with no transitive tree there is nothing else to install or audit. The cache engine and the OTLP exporter load lazily, on first use, so they are not in those figures. The size is an enforced budget in CI , not an aspiration.

Verifiable supply chain — every package publishes from GitHub Actions over OIDC with a signed npm build-provenance attestation , so you can confirm which commit and which workflow produced the tarball you installed. Each release also ships an SBOM in both SPDX and CycloneDX, and the repo is scored publicly by OpenSSF Scorecard .

Watch more

[!NOTE]

StitchAPI is at `1.0.0-rc.9`. The core runtime is feature-complete, zero-dependency, covered by a green test gate, and already running in production in two projects. We're validating in the wild before stamping a stable 1.0.0 — pin an exact version and expect only small, documented changes. Feedback is welcome.

---

Table of Contents

• What is a stitch?
• Motivation
• Why StitchAPI
• What StitchAPI is not
• Features
• Install
• Quick start
• Composition: seam, extends, .with()
• Validation & leveled drift
• Resilience: retry, throttle, timeout
• Caching
• Auth as a boundary
• Surfaces: any request style
• Four front doors
• Agent-native
• Errors & pitfalls
• Zero-infra observability
• Packages
• Documentation
• Contributing
• License

What is a stitch?

A stitch is StitchAPI's core primitive: it takes a single endpoint and hands back a callable. You declare the contract once — input, output, auth, resilience — and call it like a local function. The same definition your code calls, the CLI runs and an AI agent invokes — and every caller gets a capability, not a credential. A service with more than one endpoint is a seam — a group of stitches that share a base URL, auth, and one runtime (throttle budget, store, trace sink).

import { stitch } from 'stitchapi';

import { z } from 'zod';

const getUser = stitch({ path: 'https://api.example.com/users/{id}', output: z.object({ id: z.number(), name: z.string() }), pick: 'data', });

const user = await getUser({ params: { id: 1 } }); // typed · validated

Keep the fetch or axios you already have — it's the adapter underneath. A stitch sits _above_ the transport and turns an endpoint into a function rather than replacing the call.

Motivation

In almost every project there's a src/api/ folder of thin functions that fire an HTTP request and pull the payload out of the response. Everything that actually makes an integration reliable — auth lifecycle, retries, rate limits, timeouts, response validation, drift detection, observability — gets re-implemented at every call site, and each wrapper rots independently. fetch hands back opaque bytes, and raw bytes aren't what application code (or an AI agent) needs; both want structured, validated, observable results.

A stitch folds all of that back into the call:

Why StitchAPI

There are plenty of ways to get a typed API client — spec-based generators, hand-authored contract clients, workflow platforms, or a folder of hand-rolled fetch wrappers. StitchAPI sits in a spot none of them cover: it turns one endpoint at a time into a resilient, validated, observable function — no spec, no codegen, no config files, no server; only explicit composition.

• Atomic, not spec-first. Spec-based generators (openapi-generator, Orval, Kubb, …) need a complete OpenAPI document first — and most real-world APIs (internal, undocumented, the long tail) never get one. A stitch needs a URL and one example response.
• A runtime, not a code generator. No generated SDK to commit, diff, and regenerate. The declaration _is_ the client, validated on every live call — so a silently renamed field is a loud, leveled drift signal, not an undefined three layers downstream.
• Resilience is declared, not hand-rolled. Retries, throttling, timeouts, circuit breaking, pagination — configuration on the stitch, uniform across every integration.
• Auth is a boundary. A stitch owns its credential and lifecycle; callers get a capability, not the credential. That matters double when the caller is an AI agent.
• Agents are first-class callers. One definition is a function, a CLI command, an HTTP endpoint, and an MCP tool — returning structured, schema-validated, traceable results instead of opaque bytes.
• A library, not a platform. Zero runtime dependencies, embeds in your project, nothing to operate.

For the full competitive landscape and positioning, see the Overview.

What StitchAPI is not

Knowing what a tool refuses to be is how you trust what it is:

• Not an HTTP client or `fetch` replacement — fetch/axios are the substrate underneath; a stitch sits above the transport.
• Not a code generator — no SDK to commit, diff, and regenerate; the declaration is the runtime, validated live.
• Not spec-first — no OpenAPI document required; a URL and one example response is enough.
• Not a server to deploy — a zero-dependency library you import, for the APIs you don't control.
• Not a workflow engine or iPaaS — no orchestration, queues, or visual builder; composition is plain TypeScript.
• No config files or hidden inheritance — nothing ambient a stitch silently reads.

No server, no codegen, no config files, no implicit inheritance — only explicit composition.

Features

• One primitive, scoped to a surface — stitch(url | config) returns a typed callable; a service with more than one endpoint is a `seam` that shares base, auth, throttle budget, store, and trace sink across its members.
• Event-stream core — every call yields a typed stream (start → progress → drift → result → done); await is sugar that returns the final validated value.
• Bring-your-own validation — Zod or any Standard Schema validator (Valibot, ArkType, …); types are inferred from the schemas.
• Leveled drift detection — live responses validated against the declared schema (the contract); a required field missing/incompatible throws, while soft drift (a coercion, an undeclared or defaulted field) surfaces as a non-fatal warn / info / verbose finding instead of a silent undefined.
• Declared resilience — retry with backoff and Retry-After, pro