Use from an agent

StitchAPI is agent-native because of two choices that fall out of the stitch primitive: an agent receives a capability, not a credential — it invokes a stitch and gets back structured, validated, traceable data without ever touching the secret — and it works through one context-frugal tool, not one tool per endpoint, so adding APIs never floods the model's context window.

An agent does three things with a stitch: invokes it, authors it, and reasons over it — one subsection each.

Invoke

An agent drives stitches from a sandbox through a single code-mode tool, run_stitch, rather than a generated tool per endpoint. The agent writes a small TypeScript snippet that imports stitchapi, calls the stitch, and returns the result — list_stitches tells it what is available to call, and describe_stitch tells it the shape of one before running it.

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

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

// The agent writes this in the sandbox; run_stitch executes it.
const user = await getUser({ params: { id: 7 } });

The output schema (raw Zod here, the visible default) means the agent gets a validated, typed value back, not a guess. One tool keeps the context budget flat as the catalog grows, and the credential stays behind the boundary — the agent sees the user, never the token. Three tools make up the code-mode surface: run_stitch to execute, list_stitches to discover names, and describe_stitch to understand a stitch's shape, schema, and diagram before running it.

Author

An agent does not need a spec to add an API. Hand it a single example — a curl command, a HAR entry, or a snippet from a vendor's docs — and it emits a stitch declaration: the URL, the input shape, and an output schema inferred from the one response it saw. For the common curl/HAR case there is also a deterministic shortcut — stitch from-curl '<curl>' prints the same declaration with no model in the loop (id-like path segments lifted, credentials replaced with env()). Either way the declaration is committable code the agent (or you) can review.

Adopt in your project

Drop a short rule into your repo and any agent working in it reaches for a typed stitch instead of a hand-rolled fetch/axios whenever it adds an external API. Hand-copy the rule, or run npx stitch init to write it as AGENTS.md, a Cursor rule, or a CLAUDE.md section.

That rule teaches an agent to write stitches. A companion rule teaches it to look up how — point it at these docs over MCP so it searches the current API before answering instead of guessing from training data.

Reason over

Two outputs let an agent reason about stitches cheaply. The docs build emits an auto-generated llms.txt and a per-page llms.mdx, so an agent pulls just the one page it needs into context instead of the whole manual. And every call is a typed event stream — start → progress → drift → result → done — so the agent reads not just the final value but the retry that succeeded, the throttle that paused, and the field that drifted.

See also