Reach for stitch serve when a caller can't import your stitches in-process — a remote service, another language, a shell script — and you want to expose the registry of named stitches over a thin local HTTP front door instead.

Example

Start the server, then call a registered stitch by name with a JSON body:

# Serves the registry on http://127.0.0.1:8787 by default.
stitch serve

# List the available stitch names.
curl http://127.0.0.1:8787/

# Run the `me` stitch; the request body is its input.
curl -X POST http://127.0.0.1:8787/stitch/me \
  -H 'content-type: application/json' \
  -d '{}'

The server runs the named stitch through the same engine as an in-process call and returns the final validated result as JSON.

Options

Two routes serve the registry of named stitches:

GET / lists the available stitch names.
POST /stitch/:name runs that stitch; the JSON request body is its input. Any other method returns 405, and an unknown name returns 404.

The server binds to 127.0.0.1:8787 by default. Responses are the final validated result as JSON; send Accept: text/event-stream (or add ?stream=1) to receive the live event stream as SSE instead.

Anti-pattern: don't move the bind off the 127.0.0.1 loopback default to a public interface so a remote caller can reach it directly — the front door has no auth of its own, so a public bind turns the registry into an open proxy that runs every stitch for anyone who can reach the port. Keep it on loopback and put a fronting layer (a reverse proxy or gateway that authenticates the caller) in front of it; the stitch still holds its own credential and resolves it server-side, never handing it to the caller. See Capability, not credential.

Programmatic API

The CLI is a thin wrapper. To embed the same server in your own process, import serve from the stitchapi/serve subpath and hand it a registry of named stitches:

import { me } from './stitches';

import { serve } from 'stitchapi/serve';

const handle = await serve({ me });
console.log(`listening on ${handle.url}`);

// later
await handle.close();

serve(registry, options?) returns a handle with the bound url, port, the underlying server, and a close() method. It binds 127.0.0.1:8787 by default; pass { port: 0 } to let the OS pick an ephemeral port.

A served stitch is the same definition as the in-process function surface and the stitch CLI — one source of truth, three ways to call it.

HTTP serve

Example

Options

Programmatic API

See also

Function surface

CLI surface

MCP surface

Capability, not credential

On this page