API overview

One versioned JSON API, five authentication schemes, one response envelope. Read this page once and the endpoint reference becomes a lookup table.

What you'll actually build

Most integrations are three calls and a script tag. Before the reference, it's worth knowing which parts of the API you are likely to touch — and in what order.

Nothing in the first seven rows requires the eighth. The tag, the storefront endpoints, the server-side handoff, webhooks and MCP are a complete integration on their own — the workspace API is there when you want to script something, not a step you have to take.

Base URL and versioning

https://app.stitchwork.io/api/v1/…

The version is in the path and in the response body, and a future v2 will live alongside v1 rather than replacing it — existing clients keep working. That is a commitment, not an intention: an integration you ship this quarter is not something you will be asked to rewrite next year.

Two paths sit outside the versioned API because they are served to browsers rather than to clients: /tag/{slug}.js (the tracking script) and /q/{token} (the public quote page). There is also /healthz, if you want Stitchwork on your own status board.

Authentication

Which scheme you use depends on who is calling, not on which resource you want. That is deliberate: the credential you hand to browser JavaScript cannot read anything sensitive, and the one that can never has to leave your server.

Public key

Authorization: Public pk_live_xxxxxxxxxxxx

Or, where a custom header is inconvenient (a plain fetch, an <img> beacon), ?key=pk_live_… on the query string — accepted by the public read endpoints and the quote lookup, but not by event ingest, which requires the header.

The key is workspace-scoped and effectively write-only: nothing sensitive is readable with it, which is why embedding it in page source is fine.

Secret key

Authorization: Bearer sk_live_xxxxxxxxxxxx

Server-side only. Stored hashed, so it cannot be read back — a lost key is replaced by rotating, which issues a new pair and invalidates the old secret everywhere.

Session

This is how your team uses Stitchwork every day — they sign in and the app carries the cookie. You only need it directly if you want to script something you would otherwise click. Sign in, keep the cookie, send it on subsequent requests. The cookie is HttpOnly, SameSite=Lax, 14 days, and Secure over HTTPS.

curl -X POST https://app.stitchwork.io/api/v1/auth/login \
  -H "Content-Type: application/json" -c cookies.txt \
  -d '{"email":"ada@example.com","password":"…"}'

curl https://app.stitchwork.io/api/v1/quotes -b cookies.txt

The signed-in user resolves to exactly one workspace, and every session-authenticated request is scoped to it. There is no workspace parameter to pass or to get wrong — and a script written this way inherits its author's permissions exactly, so it can never reach a store or a channel they couldn't open themselves.

Response envelope

Success responses wrap their payload:

{
  "version": "v1",
  "data": {
    "quote": { "id": 7, "quote_number": "Q-2026-000007", "…": "…" }
  }
}

data is keyed by resource name — quote, quotes, customer, products, subscription and so on — never a bare array. A response that carries several related things carries several keys: {"quote": …, "lines": […], "activities": […]}.

Errors are flat:

{ "error": "Only draft quotes can be edited." }

Error messages are written to be shown to a human, and the app renders them directly. A few errors also carry a data block with the structured detail you need to act — the customer-delete cascade warning is the main one.

Status codes

Request format

Send JSON with Content-Type: application/json. Form-encoded bodies are also accepted for simple endpoints — the two are read through the same accessor, with form fields taking precedence. Imports additionally accept multipart/form-data and raw text/csv.

A malformed JSON body is treated as an empty one rather than erroring, so a required field will surface as a 422 naming that field rather than a parse error.

Verbs

PUT and PATCH are the same handler everywhere they both exist, and both behave as a partial update: fields you omit keep their current value. There is no full-replace semantics to trip over.

Value types

• Money is a decimal string — "2850.00" — never a float. Numbers are accepted on input and normalised to two decimal places.
• Booleans accept true, 1, "1", "true", "t", "yes" and "on". Anything else is false.
• Dates accept anything parseable; ISO 8601 is safest. Timestamps come back in ISO 8601 with an offset.
• Currency is a 3-letter ISO code, upper-cased on input.
• Country is a 2-letter ISO code.

Filtering and pagination

List endpoints take filters as query parameters, and q is a free-text search wherever it appears. Filters are exact-match unless the reference says otherwise; an empty value is ignored rather than matching empty.

Two endpoints do cap: /customers/{id}/events takes an explicit limit (1–200, default 50), and /quotes/{id}/browsing is fixed at the 50 most recent.

CORS

Only the endpoints designed to be called from a browser send CORS headers. Everything else is same-origin — the app's own JavaScript — and will fail a cross-origin call.

All send Access-Control-Allow-Origin: *. That is safe because none of them accept cookies as authentication — they take a workspace-scoped key instead, so a third-party page cannot ride a signed-in user's session.

Rate limits

One rate limit exists: event ingest, capped per workspace per minute (1200 by default; ask us if your traffic needs more). Over the cap returns 429 with {"error":"Too many events."}.

Nothing else is rate limited today. Two size limits do apply: imports are capped at 20 MB and 50,000 rows, and the product importer is allowed a ten-minute execution window because being cut off mid-file is worse than being slow.

Idempotency

There is no idempotency-key header. Instead, the operations that need to be safe to retry are keyed on natural identifiers:

Webhooks

Outbound events are documented separately — see Webhooks for the catalogue, the envelope, signature verification and the retry schedule.

Next