StitchAPI README

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 · ~25 kB min+gzip — a typical import { stitch } tree-shakes to ~22 kB, and with no transitive tree there is nothing else to install or audit. 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.7. 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, proactive throttle, layered timeouts, a circuit breaker, and idempotency keys.
• Read-through caching — opt-in response cache + in-process coalescing, keyed by a derived, principal-scoped key, loaded lazily from stitchapi/cache.
• Auth as a boundary — bearer, apiKey, basic, cookieSession (auto-login/re-login), oauth2; secrets resolve at call time and never reach the caller.
• Any request style — http by default; graphql, sse, stream, download, llm, shell, and postmessage are peer surfaces behind subpath imports.
• Pluggable state store — throttle counters and sessions behind a 3-method store; swap in Redis/Postgres to go distributed.
• Zero-infra observability — tracing is off by default; opt in per stitch or via STITCH_TRACE_* env vars. No collector, no dashboard.
• Four front doors, one definition — in-process function, CLI (stitch run), HTTP (stitch serve), and MCP (stitch mcp).
• Zero runtime dependencies — "dependencies": {}, built on global fetch, tree-shakeable; ~25 kB min+gzip for the whole entry, ~22 kB for a typical import { stitch }.

Install

npm install stitchapi@rc   # or: pnpm add stitchapi@rc · yarn add stitchapi@rc

Validation is bring-your-own — pass a Zod schema or any Standard Schema validator; none is bundled. The examples below use Zod for familiarity, and api.example.com as an illustrative host — point them at your own API to run them, or try them as-is in the playground, which serves that host from an in-browser simulator.

Quick start

The smallest stitch is a URL — declare once, call many times:

import { stitch } from 'stitchapi';

const getUsers = stitch('https://api.example.com/users');

const users = await getUsers(); // GET, parsed JSON

Path params use RFC 6570 URI templates; params, query, headers, and body all travel in one input object:

const getUser = stitch('https://api.example.com/users/{id}');

await getUser({ params: { id: 1 }, query: { expand: 'roles' } });
// → GET https://api.example.com/users/1?expand=roles

Reach for the full set of knobs only when you need them — they default off:

const getUser = stitch({
    path: 'https://api.example.com/users/{id}',
    output: User, // a validator of your choice
    pick: 'data',
    retry: 3, // ≡ { attempts: 3 }
    timeout: '5s', // ≡ { total: '5s' }
    cache: '1m', // ≡ { ttl: '1m' }
});

const user = await getUser({ params: { id: 42 } });
// → typed · validated · retried · cached

A stitch yields a typed event stream; await consumes it and returns the final value, while .safe() resolves to { ok, data, error } and .stream() yields progress, throttle waits, retries, and drift as they happen.

Composition: seam, extends, .with()

Everything reusable is a named value, and a stitch composes values — no global config is ever required. A service with more than one endpoint is a seam: declare the shared base, auth, and budget once; each endpoint is a member that inherits the config and shares one runtime (throttle bucket, store, trace sink):

import { seam } from 'stitchapi';

const api = seam({
    baseUrl: 'https://api.example.com',
    retry: { attempts: 3, on: [429, 503] },
    timeout: { total: '30s' },
});

const listUsers = api.stitch({
    path: '/users',
    output: User.array(),
    pick: 'data',
});
const getUser = api.stitch({
    path: '/users/{id}',
    output: User,
    pick: 'data',
});

For lighter reuse, extends: [fragment | stitch] merges config left→right (own fields win), and .with() pre-binds part of the input while reusing the same runtime. Full guide: Authoring.

Validation & leveled drift

The declared output schema is the contract. Wrap it in drift(): a response is validated (the call returns the validated value — coerced, defaulted, unknown keys stripped), and the difference between the raw body and that validated value is reported as a leveled, non-fatal signal:

import { drift, stitch } from 'stitchapi';
import { z } from 'zod';

const listOrders = stitch({
    path: 'https://api.example.com/users/{id}/orders',
    pick: 'data',
    output: drift(
        z.array(z.object({ id: z.number(), total: z.number().optional() })),
        {
            ignore: ['[].meta'], // acknowledged, unconsumed — don't report it
            severity: { coerced: 'info' }, // re-level a kind, or pass a level/list to filter
        },
    ),
});

Drift is schema-anchored — no snapshot to manage. Severity lives in the schema: a required field missing/incompatible is a hard invalid that throws; everything else is non-fatal drift on the event stream. Declared variance (an optional field, a nullable, an empty array) validates clean, so it's never a false alarm; ignore silences known-but-unconsumed fields and severity filters or re-levels the soft signals. The request side validates too: input takes a schema per part and fails fast before any request is sent. Full guide: Validation & drift.

Resilience: retry, throttle, timeout

The things every src/api/ folder reinvents are configuration here — uniform across every stitch:

const listUsers = stitch({
    baseUrl: 'https://api.example.com',
    path: '/users',
    retry: { attempts: 4, on: [429, 502, 503] },
    throttle: { rate: '1/s', concurrency: 2, pool: 'host' },
    timeout: { total: '30s', each: '10s' },
});

throttle is proactive (keeps you under a limit before it bites; pool: 'host' shares a limiter across stitches), retry is reactive (backoff + Retry-After), and timeout aborts with a real AbortSignal. Three more knobs round it out: circuit fast-fails a dependency that's already down, idempotency injects a stable Idempotency-Key on writes, and verdict declares what counts as success — accept treats a non-2xx (e.g. 404) as a normal result instead of a throw, flag fails a 200 whose body says it failed. Full guide: Resilience.

Caching

A read-through response cache with in-process request coalescing — off by default, loaded lazily from stitchapi/cache only when a stitch sets cache. The key is derived from the resolved request (no caller-authored keys to drift) and principal-scoped by default, so user A is never served user B's cached response:

const getUser = stitch({
    path: 'https://api.example.com/users/{id}',
    output: User,
    pick: 'data',
    cache: '5m',
});

const listAnnouncements = stitch({
    path: 'https://api.example.com/announcements',
    output: z.array(z.object({ id: z.number(), title: z.string() })),
    pick: 'data',
    cache: {
        ttl: '1h',
        tenancy: 'app',
        vary: ['accept-language'],
        entries: 500,
        fingerprint: 1, // pins the shape — cacheable without a fingerprinter
    },
});

Caching is sound by construction: a stitch with an output schema caches only when that schema can be fingerprinted or you pin a fingerprint tag — otherwise it refuses to cache rather than serve a stale shape. Mark sensitive data sensitive: true to opt out entirely.

Auth as a boundary

Auth is a field on the stitch — never global. Secrets resolve at call time (env(), secretsFile()), the declaration is committable, and the caller gets data without ever seeing the credential:

import { stitch } from 'stitchapi';
import { bearer, env } from 'stitchapi/auth';

const getUser = stitch({
    path: 'https://api.example.com/users/{id}',
    auth: bearer(env('API_TOKEN')), // resolved per call; the caller passes no secret
});

bearer, apiKey, and basic are header strategies; oauth2() runs the client-credentials grant and caches/refreshes the token; and cookieSession runs a login, captures the cookie, replays it, and re-logs-in when the wall returns — the caller never sees the password or writes the cookie dance. Full guide: Auth.

Surfaces: any request style

A surface is the request style a stitch speaks. http is the default; the rest are peer surfaces on the same engine — auth, retry, throttle, timeout, validation, and the event stream compose with every one. Each ships as its own subpath import, so import { stitch } pulls in http alone.

Full guide: Surfaces.

Four front doors

The same typed unit is reachable four ways, so humans and agents call exactly the same validated, observable thing:

stitch run streams every event as one JSON line on stdout (ready for jq); stitch trace summarizes the run log — runs, failures, retries, drift, and latency percentiles. Full guide: Surfaces → CLI.

Agent-native

A stitch is built to be invoked by an AI agent. Auth lives on the stitch, so an agent gets a capability, not a credential. And rather than one MCP tool per endpoint (which floods the model's context), an agent drives a single code-mode tool, run_stitch: it writes a small TypeScript snippet that imports stitchapi and calls the stitch, with list_stitches and describe_stitch for discovery — so the context budget stays flat as the catalog grows.

Authoring is agent-friendly too — hand an agent one curl/HAR/doc example and it emits a stitch declaration, with a deterministic shortcut for the common case:

$ stitch from-curl 'curl https://api.example.com/users/7 -H "authorization: Bearer …"'
# prints a ready-to-commit stitch: id-like segments lifted to {params}, secrets → env()

stitch init writes the “declare a stitch, don't hand-roll fetch” rule into the files coding agents read (AGENTS.md, Cursor/Windsurf/Cline rules, a CLAUDE.md section), and the docs build emits an auto-generated llms.txt. Full guide: Use from an agent.

Errors & pitfalls

A failed stitch throws a StitchError — an Error subclass carrying .status, .attempts, and (for response failures) .body (the parsed error payload, on a non-enumerable channel that never reaches a trace sink) and .url. Prefer branching? .safe() resolves to { ok, data, error }. Branch on .status and .attempts (plus instanceof RateLimitError) — the STITCH_* names below are documentation IDs, not runtime values, so there is no error.code to match on:

Full catalog: Errors & pitfalls.

Zero-infra observability

Observability is a consumer of the event stream, not a separate system — and it's off by default. Opt in per stitch (trace: 'console' / fileSink(path) / a TraceSink) or globally with env vars — no collector, no dashboard, nothing to deploy:

STITCH_TRACE_CONSOLE=1 node app.js          # live, colored, one line per event on stderr
STITCH_TRACE_FILE=./run.jsonl node app.js   # append JSONL to a path
STITCH_EXPORT=otlp node app.js              # also fan events to an OTLP collector

Built-in sinks scrub secrets at the sink boundary (the live request is never touched). stitch trace summarizes the JSONL; @stitchapi/pino ships the same events as structured logs.

Packages

This repository is a pnpm workspace. The published library is stitchapi; the rest are thin, peer-dependency integrations that add no capability of their own. The table below is generated by pnpm gen:readme (and verified in CI by pnpm check:readme): it lists every publishable workspace package, so it never drifts as packages are added. Each package's own README links to it on npm.

Documentation

The full documentation site lives at stitchapi.dev — Quickstart, per-feature Guides, Concepts, Surfaces, For agents, and the generated Reference.

The published library's own README (what npm renders) is in packages/core/README.md. Design notes live in docs/: Feature Lenses, Overview, Design.

Contributing

Local setup, the dev loop, the bundle-size budget, and the worktree + PR workflow are documented in CONTRIBUTING.md.

License

Apache-2.0