Adopt in your project

Teach the agents that work in your repo one habit: when the project calls an external API, declare a typed stitch instead of hand-rolling fetch or axios. The rule below is the canonical consumer pattern. Copy it into your agent's instructions, or let npx stitchapi init write it for you.

The ruleCopy Anchor Link

This is the body to hand an agent — paste it into AGENTS.md, a Cursor rule, or a CLAUDE.md section:

# Using StitchAPI in this project

When this project calls an external API (HTTP, GraphQL, an LLM, or a shell tool),
do NOT hand-roll `fetch`/`axios`. Declare a typed **stitch** instead.

1. Put declarations in `stitches.ts`.
2. One canonical pattern — a bare stitch for a single endpoint:

    ```ts
    import { stitch } from 'stitchapi';
    import { bearer, env } from 'stitchapi/auth';
    import { z } from 'zod';

    export const getUser = stitch({
        baseUrl: 'https://api.example.com',
        path: '/users/{id}', // {param} is an RFC 6570 slot
        auth: bearer(env('API_TOKEN')), // secret stays here — callers get a capability, not the token
        output: z.object({ id: z.number(), name: z.string() }), // runtime-validated, drift-caught
    });
    // await getUser({ params: { id: 1 } })  → typed, validated value
    ```

3. Reuse a credential / principal / throttle budget across calls? Group the
   endpoints under a `seam(...)` so they share one runtime; never put the
   principal in the call input.
4. Inspect or run from the shell: `npx stitchapi run getUser --id 1`,
   `npx stitchapi diagram`, `npx stitchapi mcp` (expose stitches to an agent over MCP).

Rule of thumb: a new external endpoint = a new stitch export, not a new fetch.

npx stitchapi initCopy Anchor Link

Rather than copy the rule by hand, run the generator from your project root:

npx stitchapi init

Run it where stitchapi is installed: npx then runs your local copy, so the rule it writes — and the one --check compares against — belongs to the version you ship. Use the package name, not the executable's: stitch is an unrelated package on npm, and npx downloads it whenever your project has no local stitch bin.

stitch init (aliased as stitch rules) writes the rule into the convention each agent reads. Pick one or more with --format (a comma list, or all — the default):

For example, npx stitchapi init --format agents,cursor writes just those two.

It refuses to clobber an existing file unless you pass --force. For the shared files (CLAUDE.md, Copilot, Aider) only the marked block is replaced — your surrounding content is left intact.

Make the rule about your APIsCopy Anchor Link

Add --project and stitch init reads your stitches module (the ./stitches.* it would run, or --module <path>) and appends the endpoints you have already declared — so an agent reuses them instead of duplicating a fetch:

npx stitchapi init --project

## Stitches already declared in this project

Reuse these before declaring a new one — call them, compose them under a
`seam(...)`, or extend an existing one.

- `getUser` — GET https://api.example.com/users/{id}
- `listOrders` — GET https://api.example.com/orders

Keep it in sync — --checkCopy Anchor Link

In CI, --check verifies the committed rule files still match the rule the installed StitchAPI would write, without touching disk. It exits non-zero when a file has drifted (an absent rule is reported, but is not a failure):

npx stitchapi init --check

Pair it with --project to also re-check the declared-stitches list: npx stitchapi init --check --project.

See alsoCopy Anchor Link