API v2 — Overview

STOQ's AI-native API. v2 is a ground-up rewrite designed so a developer — or an AI agent — can turn a natural-language intent into a single, correct call. Instead of REST resources with overloaded update calls, it ships intent-bearing actions — release, charge_balance, set_delivery_date — alongside one predictable, deep-partial PATCH per capability for plain settings.

What makes it AI-native

• Self-describing actions. Every action registers its description, aliases, notes, verb, and a real JSON request_schema — so an agent can map "charge the remaining balance" to exactly one call, with the required fields and gotchas attached.
• A built-in discovery surface. GET /help returns the full manifest, skill.md is an unauthenticated agent-readable guide, and llms.txt is the root index — an agent can learn the whole API before it even has a token.
• MCP-first. Every action is also exposed as an MCP tool, so agents can drive STOQ without touching HTTP.
• Predictable writes. Named POST actions carry side effects; one deep-partial PATCH per capability carries plain settings and toggles. No guessing which field combination means what.

Quick links

Resources

Design at a glance

• One verb-and-path per action. Every action class registers itself with a description, aliases, notes, path, and verb.
• Named actions carry side effects; PATCH carries settings. A named POST action exists only when the operation does more than write settings — state transitions, Shopify mutations, variant fan-out. Plain settings and all boolean toggles (e.g. badge.enabled, terms.enabled, remaining_balance.auto_collect) go through the capability's deep-partial PATCH. Each PATCH action's manifest notes list its toggleable field paths.
• Catch-all dispatcher. Every path under /api/v2/external/* is matched against ApiV2::Registry — no per-route wiring.
• Discovery primitives. GET /api/v2/external/help returns the full manifest (scoped via ?prefix= or GET <scope>/help at any URL level). GET /api/v2/external/preorders/skill.md is an unauthenticated, AI-readable usage guide. GET /llms.txt is the root index. And every action is also an MCP tool.
• Same auth model as v1. X-Auth-Token header carrying the shop API key. Rate-limiting and points budget are identical (1 pt read, 2 pt write).
• Standardized async jobs. Bulk and long-running actions return 202 Accepted with {job_id, status_url}. Poll the status URL until a terminal status.

What "action-driven" buys you

For a human:

curl -X POST https://app.stoqapp.com/api/v2/external/preorders/orders/{order_id}/payments/charge_balance \
  -H "X-Auth-Token: $STOQ_API_KEY"

…instead of working out which combination of fields on a giant order PATCH means "charge the remaining balance now".

For an AI agent:

• aliases on every action map natural-language phrasings to a single canonical call — and the capability PATCH actions carry aliases for their toggles too ("turn on auto-collect" resolves to PATCH .../payments with remaining_balance.auto_collect: true).
• notes carry the gotchas (e.g., release: "Returns 409 if balance hasn't been collected; pass force: true to override.").
• request_schema in the manifest is a real JSON Schema — required fields, enums, and bounds included.
• /help returns the full manifest so the agent can plan multi-step workflows without having to re-read docs each turn — or skip HTTP entirely and connect to the MCP server, where every action is a tool.

See Dispatch & Discovery for the full discovery surface.