Getting Started

Base URL

https://app.stoqapp.com/api/v2/external

All v2 endpoints live under this prefix.

Authentication

v2 uses the same auth scheme as v1 — an X-Auth-Token header carrying the shop’s API key.

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

You can find your API key in the STOQ app: Back in stock alerts → Settings → Integrations → API (under Developer; press Copy). See API Key for the full walkthrough.

A missing or invalid token returns 401 Unauthorized.

Rate limits

Identical to v1 — 360 points per 60s rolling window. Reads cost 1 point, writes cost 2.

The same X-RateLimit-* headers are present on every response. See Rate Limits for details.

Your first call

The simplest health check is /help — it returns a manifest of every action the API exposes.

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

Filter to a single resource — either with the prefix param or by appending /help at any URL level:

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

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

Response envelope

Successful responses are returned bare — the action’s data payload at the top level, with no wrapper. Reads return 200 OK; writes return 202 Accepted (see Errors & Responses).

{ "id": "uuid", "name": "Spring Drop", "...": "..." }

Errors are returned wrapped under an errors array:

{ "errors": ["mode must be one of: auto, manual"], "details": [{ "code": "invalid_params", "message": "must be one of: auto, manual", "path": "mode", "value": "xyz", "expected": { "type": "string", "enum": ["auto", "manual"] } }] }

See Errors & Responses for the full table.

Where to go next

• Browse capabilities by resource: start with Offer for the most common selling-plan flows.
• Plan AI integrations: read Dispatch & Discovery — the /help manifest and skill.md are built for this. Every action is also exposed as an MCP tool — see MCP.
• Run bulk jobs: the Bulk & Async Jobs page explains the job_id polling pattern used everywhere from CSV exports to bulk order cancellation.