Home
Guide

Getting Started

Authenticate and make your first v2 API call.

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: Settings → Integrations → API Key. 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"] }

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.
Built withSourcey