Guide
Migrating from v1
How the v1 REST endpoints map to v2 actions, and why the action model.
The v1 API is REST-style: resources with GET/POST/PUT/DELETE and overloaded update calls. v2 is action-driven — every operation is a self-describing action with a verb, a path, aliases, and a JSON request schema. Both are fully supported; migrate when it suits you.
What changes
| v1 (REST) | v2 (actions) |
|---|---|
PUT /preorders/{id} with a grab-bag of fields | A named action per side effect (e.g. enable, disable, set_delivery_date) plus one deep-partial PATCH per capability for plain settings |
| Figure out which field combo triggers a behavior | One action = one intent; required fields and gotchas are in the action's notes/request_schema |
| Read the docs to discover endpoints | GET /help returns the full manifest; skill.md and llms.txt describe the API to agents |
| HTTP only | Every action is also an MCP tool |
Same as v1
- Auth — the same
X-Auth-TokenAPI key. - Rate limits — the same points budget (1 pt read, 2 pt write).
- Base concepts — offers (selling plans), variants, intents (signups) are unchanged.
How to map a call
- Find the capability (
offers,orders,reports,signups, …). - For a state change or side effect, use the named action — e.g.
POST /preorders/offers/{id}/enableinstead ofPUT-ingenabled: true. - For plain settings/toggles, use the capability's deep-partial
PATCH— its manifestnoteslist the field paths. - Unsure of the exact shape?
GET /api/v2/external/help?prefix=/preorders/offersreturns the manifest for that scope.
See Getting Started for the base URL and auth, and the API v2 Reference for every action.
