How do I install StitchAPI Docs?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does StitchAPI Docs need an API key?

No required environment variable is listed on this record.

What transport does StitchAPI Docs use?

StitchAPI Docs is reached over HTTP.

When was StitchAPI Docs last checked?

Last checked 2026-11-08. Search and read the StitchAPI docs: search_docs finds relevant sections, get_doc reads a page.

StitchAPI Docs MCP server

[!NOTE]

StitchAPI is at 1.0.0-rc.8. 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.

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:

Around raw `fetch`, you hand-roll…	…a stitch declares it once
Opaque bytes you parse and hope are the right shape	Schema-validated, typed results — drift caught on every call
A throw on the first failure, then it's on you	Retries with backoff + jitter, honoring `Retry-After`
One coarse timeout, if you remember it	Layered total / per-attempt timeouts with real aborts
No rate control — you meet the 429s in production	Proactive throttle: rate + concurrency caps, shared per host
A raw byte stream you frame and paginate yourself	SSE framing, delta concatenation, auto-pagination
Zero visibility into what the call did	A typed event stream + opt-in traces: latency, retries, drift

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.

Alternative	Needs	You maintain	StitchAPI instead
Spec-based codegen (openapi-generator, Orval, Kubb, …)	a complete OpenAPI spec	a generated SDK, regenerated on every API change	one endpoint at a time, validated live at runtime
Typed runtime clients (Zodios, ts-rest, …)	a hand-authored contract	your own retry / auth / rate-limit code around it	resilience, auth lifecycle, and drift detection built into the primitive
Workflow platforms (Windmill, n8n, …)	a server to deploy	flows inside someone else's runtime	a zero-dependency library; composition is just code
Hand-rolled `fetch` wrappers	nothing	bespoke auth, retries, limits — re-solved per project	the same concerns, declared once per stitch

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 state, cache and sessions behind a get/set store with optional atomic verbs; 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 ().

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:

Change	What it means	Level
invalid	a required field missing or incompatible — throws	`error`
coerced	a coercion (`"42"`→`42`): a wire-type shift validation hid	`warn`
undeclared	a key the schema strips	`info`
defaulted	a `.default()` fired (field absent)	`verbose`

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
            level: { 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 level 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(), credential.file()), 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.

Surface	Import	Shapes	`await` resolves to
`http`	`stitch` (default)	a JSON-over-HTTP call	the validated body
`graphql`	`stitchapi/graphql`	POST `{ query, variables }`, picks `data`	the `data` payload
`sse`	`stitchapi/sse`	a `text/event-stream` reader (over fetch)	every parsed event, collected
`stream`	`stitchapi/stream`	a raw `ReadableStream` reader	every decoded chunk, collected
`download`	`stitchapi/download`	a buffered binary GET	`{ blob, filename }`
`llm`	`stitchapi/llm`	a chat-completion via a provider contract	the normalised `{ text, … }`
`shell`	`@stitchapi/shell` (peer pkg)	a local command, args + stdin	the command's stdout
`postmessage`	`stitchapi/postmessage`	a typed iframe ↔ parent RPC / event call	the typed RPC response

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:

Front door	How	Example
In-process function	import and call	`await listUsers()`
CLI command	`stitch run`	`$ stitch run listUsers`
HTTP endpoint	`stitch serve`	`POST /stitch/listUsers`
MCP / agent tool	`stitch mcp`	`run_stitch { "name": "listUsers" }`

The three non-function doors address a stitch by its export name, the same name list_stitches and GET / list.

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:

Catalog ID	When
`STITCH_VALIDATION`	a response failed its output schema
`STITCH_DRIFT`	a response drifted past the level you allowed
`STITCH_AUTH_WALL`	auth failed, or a soft `200` login wall couldn't be refreshed
`STITCH_TIMEOUT`	a call exceeded its timeout budget
`STITCH_CIRCUIT_OPEN`	the circuit breaker is open after repeated failures
`STITCH_GRAPHQL`	a GraphQL response came back `200` but carried an `errors` array
`RateLimitError`	a delegate-backoff stitch surfaced a rate-limit for an outer gate

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

StitchAPI Docs

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install StitchAPI Docs?

Does StitchAPI Docs need an API key?

What transport does StitchAPI Docs use?

When was StitchAPI Docs last checked?

Documentation

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

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install StitchAPI Docs?

Does StitchAPI Docs need an API key?

What transport does StitchAPI Docs use?

When was StitchAPI Docs last checked?

Documentation

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

Composition: seam, extends, `.with()`