Theme Maestro APIv1.0.0

The Theme Maestro API lets you read your own store's Theme Maestro data from your own code: a spreadsheet sync, an internal dashboard, a warehouse system, or an AI assistant.

It is a JSON API over HTTPS. Every request is authenticated with a token you create yourself inside the app, and every request only ever sees the store that token belongs to — there is no way to ask for another store's data, and no store id to pass.

• Base URL — https://api-staging.sappo.xco.agency
• Shape — GET https://api-staging.sappo.xco.agency/theme/v1/{resource}
• Authentication — Authorization: Bearer mak_…
• Machine-readable reference — OpenAPI 3.0 document

Responses are always JSON. A successful resource response carries a data array and a meta object; a failed one carries a single error object and nothing else.

No endpoint changes your data: everything here is a read.

Get a token

Open the app in your Shopify admin, go to Settings → API Access, and create a token. The full token is shown once, at creation time; afterwards only its first 12 characters are stored in readable form. If that card is locked, API access is not included in your current plan and the app will not create a token until the plan changes. At most three tokens can be active at once, so revoke one you no longer use before creating another.

A token can be given an optional expiry date, and can be revoked at any time from the same screen. Revoking takes effect on the next request.

Send the token

Put it in the Authorization header of every request, after the word Bearer:

curl "https://api-staging.sappo.xco.agency/theme/v1/scheduled-themes" \
  -H "Authorization: Bearer mak_your_token_here"

There is no other accepted form: a query-string token, a cookie, or a different header name is rejected with MISSING_TOKEN.

Keep it secret

The token carries everything this API can do with your whole store's data in this app, so treat it like a password:

• Store it in a server-side secret, not in a browser, a mobile app, or a public repository.
• Never call this API directly from a storefront page — the token would be visible to every visitor.
• Create one token per integration, so you can revoke a single one without breaking the others.

A token is stored only as a SHA-256 hash, so nobody — including us — can read it back to you. If you lose it, create a new one and revoke the old.

Every resource endpoint is a GET on a resource list:

GET https://api-staging.sappo.xco.agency/theme/v1/{resource}

{resource} is one of the names listed under Resources below. The v1 segment is the API version (see Versioning).

Ask for JSON and read JSON back:

curl "https://api-staging.sappo.xco.agency/theme/v1/scheduled-themes?page=1&page_size=50" \
  -H "Authorization: Bearer mak_your_token_here" \
  -H "Accept: application/json"

A successful response is always this shape:

{
  "data": [ { "id": 1 } ],
  "meta": { "page": 1, "pageSize": 50, "total": 137 }
}

data holds the records for the page you asked for, in the resource's own field names. meta describes the page.

Each resource's example response below is abridged: a record carries every column stored for it, so expect fields the example does not show. Some resources return customer details, email addresses or codes among them — read the resource's own description before you log, cache or forward a response.

These documentation endpoints need no token at all, so you can explore before you create one:

Lists are paged with two query parameters:

Note the asymmetry: the request parameter is page_size (snake case), while the field echoed back in meta is pageSize (camel case).

"meta": { "page": 2, "pageSize": 25, "total": 137 }

total is the number of records matching your filters, not the number on this page. Walk the list until page * pageSize >= total:

# 137 records at 25 per page = 6 pages
for page in 1 2 3 4 5 6; do
  curl -s "https://api-staging.sappo.xco.agency/theme/v1/scheduled-themes?page=$page&page_size=25" \
    -H "Authorization: Bearer mak_your_token_here"
done

Records are returned newest first. Which timestamp "newest" means depends on the resource — creation time for most, last-change or scheduled time for a few — and each resource's description below says which. Because new records can arrive while you page, a long walk can show a record twice or skip one; if that matters, page from the last page backwards, or filter to a window that has stopped changing.

Any query parameter other than page and page_size is passed to the resource as a filter. Each resource accepts its own set — the supported names, types and allowed values are listed per resource under Resources below, and in the OpenAPI document.

# Only the records a resource's own `status` filter matches
curl "https://api-staging.sappo.xco.agency/theme/v1/scheduled-themes?status=PENDING" \
  -H "Authorization: Bearer mak_your_token_here"

Three things to know:

• An unknown filter is ignored, not rejected. A misspelled parameter returns the unfiltered list with 200, so check your spelling against the resource's parameter list if a result looks too large.
• Filters combine with AND. Passing two filters narrows the list to records matching both.
• Booleans accept the usual spellings — true, 1, yes, on are true; anything else is false.

Filters apply before paging, so meta.total reflects the filtered count.

Every failure of a resource endpoint returns the same envelope, with the HTTP status repeated inside the body so it survives logging:

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Token is invalid, expired, or revoked.",
    "status": 401
  }
}

Branch on error.code, never on error.message — the wording may be improved, and we aim to keep the codes stable within a version. The table under this section lists every code a resource endpoint can return, and what to do about each.

Two cases are worth calling out because they look like one another:

• MISSING_TOKEN means the Authorization header was absent or did not begin with Bearer . Your request never reached a token lookup.
• INVALID_TOKEN means a token was sent but did not pass: it does not exist, it was revoked, it expired, or the store is suspended. The API deliberately does not tell you which, so a token cannot be probed.

Each token may make 60 requests per 60 seconds. The budget is per token, not per IP address, so splitting work across machines does not raise it — creating a second token for a second integration does.

Every successful response carries your current standing:

Over the limit you get 429 with error.code of RATE_LIMITED, plus a Retry-After header holding the number of seconds to wait. The 429 response repeats X-RateLimit-Limit, X-RateLimit-Remaining (always 0) and X-RateLimit-Reset.

Honour Retry-After rather than retrying immediately:

response=$(curl -s -D headers.txt "https://api-staging.sappo.xco.agency/theme/v1/scheduled-themes" \
  -H "Authorization: Bearer mak_your_token_here")
# on 429: sleep "$(grep -i '^retry-after:' headers.txt | tr -dc '0-9')"

For a large export, prefer a bigger page_size over more requests: one request for 100 records costs the same budget as one request for a single record.

The documentation endpoints are not metered by this budget.

The version is the v1 segment in the path, and this documentation describes release 1.0.0.

Inside v1 we aim to make only additive changes: a new resource, a new filter, or a new field on a record. Treat unknown fields as something to ignore rather than something to fail on, and your integration will keep working.

A change that could break a reader — a field removed or renamed, a filter's meaning changed, a status value dropped — belongs on a new path segment (v2), with v1 still answering. Bug fixes are the exception we do make inside v1: where a list was ordered by the wrong column, correcting it changes what page one returns.

info.version in the OpenAPI document is the documentation release; the path segment is the API contract. Pin the path segment in your code, and re-read the document when info.version changes.

The Model Context Protocol (MCP) is an open standard that lets an AI assistant call tools on a server instead of guessing from text: you connect the assistant once, it discovers which tools exist, and then it can answer "how many claims are still pending?" by actually querying your store rather than inventing a number. Claude Desktop, Claude Code and a growing list of other clients speak it.

Theme Maestro exposes the same data as this API over MCP at https://api-staging.sappo.xco.agency/theme/mcp, authenticated with the same mak_ token in the same Authorization header. No separate signup, no second credential.

The tool list, the exact client configuration to paste, and the errors to expect are on the MCP guide, with a machine-readable copy at https://api-staging.sappo.xco.agency/theme/docs/mcp.json.