Skip to content

Requests and answers

Paths, how arguments travel, what answers look like and the limits on a request.

Updated

Paths

Every path is under the API’s base, https://api.sherpo.io/merchant, and starts with /v1 (see versioning):

  • A store’s operations are under /v1/stores/{store}, where {store} is the store’s id, as GET /v1/merchants lists them: GET /v1/stores/{store}/products, POST /v1/stores/{store}/products/{product}/publish.
  • The business is GET /v1/merchants and GET /v1/merchants/{merchant}.

A row is named by its id in the path (/products/{product}). Products and the other kinds whose reference says so also take their slug as slug:<slug>, so /products/slug:watercolor-basics names the product whose slug is watercolor-basics. An entry’s slug is unique only within its product, so /products/{product}/entries/{entry} takes its id alone.

A row that belongs to a product is named under it: PATCH /products/{product}/tiers/{tier}, GET /products/{product}/entries/{entry}, and a quiz under its entry too, GET /products/{product}/entries/{entry}/quizzes/{quiz}. The same holds for prices, prompts, reviews, attempts, certificates and their issues, feeds, an event’s sessions and a portfolio’s holdings. A row that isn’t the named product’s (or a quiz that isn’t the named entry’s) answers 404 not_found.

Some lists answer for the whole store and for one product, as two operations: GET /reviews lists every product’s reviews, and GET /products/{product}/reviews one product’s. The store-wide lists are /reviews, /reviews/stats, /tiers, /prices, /certificates/issues, /attempts and /feeds, each also under /products/{product}. A product’s certificates are listed under it alone, at GET /products/{product}/certificates.

A path that answers no operation is 404 not_found; a path that answers other methods is 405 method_not_allowed, with an Allow header listing them. A HEAD answers as its GET does, without the body, except on a file’s URL, which takes GET alone (see files).

Arguments

  • Path parameters name the rows the call acts on.
  • A write’s other arguments are a JSON object in the body. Send Content-Type: application/json; an operation that takes nothing but its path takes an empty body or {}.
  • A read’s or a delete’s other arguments go in the query string: scalars as they are (limit=50), objects one level deep (span[from]=2026-11-01), arrays as the parameter repeated (ids=a&ids=b), and a reference to a row as its id (product=<id>, or product=slug:<slug>). Percent-encode each value on its own, so a value holding a comma stays one value.
  • A read whose arguments don’t fit the query string (an array of objects) is a POST to its /query path with a JSON body, like POST /access_requirements/query. It still only reads, which the OpenAPI document marks with x-read-only: true.

Each operation’s arguments, their types and limits are in its reference page. An argument an operation doesn’t take, a value outside its limits, or a body that isn’t a JSON object is refused as 422 invalid, with context.path pointing at it (["body", "title"], ["query", "limit"]).

Answers

A call answers JSON: 201 for an operation named create or record (POST /products, POST /orders), 200 for every other, granting access and attaching a file included. Each operation’s reference page names its status. A failure answers a problem instead.

  • Names are snake_case.
  • Times are ISO 8601 strings in UTC (2026-11-03T10:00:00.000Z). A time you send may carry an offset (2026-12-01T09:00:00+01:00), and a date-only filter takes YYYY-MM-DD.
  • Money is an integer in minor units with the exponent that scales it and the currency (lowercase ISO 4217): { "amount": 4900, "exponent": 2, "currency": "eur" } is 49.00 euros. Send amounts the same way.
  • Ids are opaque strings. Store them as they are; never parse them.
  • Rich text fields come back as HTML in one closed format. See rich text.
  • Enum values may grow within /v1: treat a value you don’t know as “other”, never as an error. See versioning.

Short answers

A write that takes a long text or binds files answers short, so you don’t pay for what you just sent: a body write (PUT /{kind}/{id}/body, its edit, its publish) answers its attachment, the asset it holds now (the from of your next write) and the attachments it created, with the preview link a set or an edit answers and the blocks an edit touched; a product, entry, page or quiz write answers the record without its long texts, attachments and files, with the attachments its texts created. Pass full: true with the write to have them answered too, as its read answers them. Each operation’s reference page marks what only full answers.

Every write answers Cache-Control: no-store, so no cache keeps what it answered (a webhook’s signing secret among them).

Limits on a request

  • A body of more than 16 MiB answers 413 with the problem type invalid.
  • A body nesting deeper than 64 levels, or holding more than 100,000 objects and arrays or 100,000 values, answers 422 invalid.
  • Calls are metered per token, on each store on its own: see rate limits.

Type to search…

↑↓ navigate↵ selectEsc close