Integrating AI agents

The v2 API is designed so an AI agent can operate it without baked-in knowledge of STOQ. Every action self-describes with a description, natural-language aliases, notes, and a request schema — and that metadata is served live from the same registry that handles dispatch, so it can never drift from what the API actually accepts.

There are two ways to consume this:

• MCP — if your agent runs in a tool-calling client (Claude Code, Claude Desktop, Cursor, or your own MCP-capable harness), connect it to the MCP server. Each action arrives as a ready-made tool; no prompt engineering needed.
• skill.md + /help — if you're building a prompt-based agent (a support bot, a workflow tool, anything that composes its own HTTP calls), use the discovery endpoints on this page.

skill.md — the system-prompt guide

GET https://app.stoqapp.com/api/v2/external/preorders/skill.md

Public, no auth, plain markdown. Paste it verbatim into your agent's system prompt, or save it as a SKILL.md your agent loads on demand. It teaches the agent:

• base URL, auth, and content type
• the core idea (action-driven, alias-matched — not REST-resource-shaped)
• the key conventions (PATCH for settings, named actions for side effects, the lifecycle state machine, 202 + job_id for async writes)
• worked example flows ("change the preorder button text on the summer drop", "pause and stop overselling", translations, scheduling)
• a live table of every registered preorder action with method, path, description, and aliases

Because the action table is generated from the live registry at request time, re-fetching skill.md is how your agent picks up new capabilities — there's no version to pin.

llms.txt — the root index

GET https://app.stoqapp.com/llms.txt

Also public. A discovery breadcrumb (think robots.txt for agents) that lists every per-domain skill.md plus the auth and manifest pointers. Each API domain gets its own skill document so an agent can ingest just the surface it needs; as more domains ship (back-in-stock v2, etc.) they appear here.

The /help manifest workflow

skill.md is prose for the prompt; /help is structured data for building requests. It requires the API token:

curl https://app.stoqapp.com/api/v2/external/help \
  -H "X-Auth-Token: $STOQ_API_KEY"

Each entry carries everything needed to construct a call:

{
  "name": "set_button_text",
  "method": "POST",
  "path": "/preorders/offers/:id/widget/set_button_text",
  "description": "Set the preorder button's call-to-action label.",
  "aliases": ["change button text", "rename button", "set button label",
              "change preorder button label", "update button text"],
  "path_params": ["id"],
  "request_schema": {
    "type": "object",
    "properties": { "text": { "not": { "type": "null" } } },
    "required": ["text"]
  }
}

The loop your agent runs:

1. Fetch the manifest (once per session, or scoped — see below).
2. Match the merchant's phrasing against the aliases arrays. "Rename the preorder button" → set_button_text. The aliases are written in merchant vocabulary on purpose; semantic matching against them is far more reliable than matching against paths.
3. Build the request from request_schema (the JSON body, with its required list) plus path_params (substitute each :placeholder in path — fetch GET /preorders/offers first when the merchant gave a name instead of an ID).
4. Call it against https://app.stoqapp.com/api/v2/external + the action's path, with X-Auth-Token. Read notes first — that's where the gotchas live (e.g. which field paths a PATCH toggles, or when a force: true is required).

Errors come back as { "errors": [...] } with the status codes documented in Errors & Responses — in particular, 409 Conflict means an invalid lifecycle transition whose message names the unblocking action. Surface it to the model; don't retry.

Scoped help for narrow contexts

The full manifest is large (~187 actions). When your agent only operates a slice of the API, load just that slice:

# Query-param form
curl 'https://app.stoqapp.com/api/v2/external/help?prefix=/preorders/orders' \
  -H "X-Auth-Token: $STOQ_API_KEY"

Scoped help is also reachable at any URL level via the dispatch catch-all — /preorders/offers/help, /preorders/offers/:id/widget/help, and so on. The offer-scoped form (/preorders/offers/:id/help) additionally includes current-state hints for that specific offer, which is useful right before a lifecycle action.

This keeps token usage down and intent-matching sharp: an agent that only manages preorder orders never needs the widget-styling actions in context.

Which approach should I use?

All three are views over the same action registry, so capabilities, aliases, and request schemas are always identical across them.