// developers
Magistry exposes the same tool registry its own assistant uses — as a REST API and as a remote MCP server. Every tool is tagged read, auto_write or propose_write, a propose_write lands as an approval card, and every call is scoped to exactly what you granted.
// auth
Minted on the Developers page (Settings → Developers), scoped at creation — ads:read, catalog:write, or the read / write / admin bundles. Sent as a Bearer token on every call.
Authorization: Bearer mag_sk_live_…
No store yet? “Try the API on demo data” on the same page gives you a mag_sk_sbx_ key on a private copy of the demo shop for 7 days. Reads return real-shaped data; writes answer with what they would do and change nothing.
The MCP server ships a full authorization server with PKCE. Clients register with a Client ID Metadata Document (dynamic client registration still works until its announced sunset). On connect you pick the store and the scopes — the client never sees more than you granted. Bearer API keys work here too.
https://app.magistry.io/api/mcp
Writes are either auto_write or propose_write. A propose_write returns an approval card the operator confirms in the dashboard. Auto-apply is opt-in, per credential, in Settings → Developers. Writes that hand authority back (releasing the kill switch, turning automation on, declaring ownership of a field) always wait for the operator, whatever auto-apply says. Stopping is immediate.
"status": "proposed", "applied": false
// the tool registry
Revenue, spend, profit, open approvals — the same overview the dashboard renders.
POST /api/v1/tools/get_store_overview
Catalog state — lifecycle, tiers, cost confidence, per-product performance.
POST /api/v1/tools/query_products
Order and revenue rollups over any window, per store.
POST /api/v1/tools/get_orders_summary
Daily performance series — spend, revenue, ROAS across channels.
POST /api/v1/tools/query_performance
Draft a discount campaign. Lands as an approval card the operator confirms.
POST /api/v1/tools/propose_discount
Reprice a variant on Shopify. Approval-gated unless auto-apply is opted in.
POST /api/v1/tools/shopify_update_variant_price
// examples
curl -X POST \
https://app.magistry.io/api/v1/tools/query_performance \
-H "Authorization: Bearer mag_sk_live_…" \
-H "Content-Type: application/json" \
-d '{ "window_days": 30 }'
# writes go through the same shape —
# a propose_write returns an approval card
# ("status": "proposed", "applied": false)
# that the operator confirms in the dashboard
curl -X POST \
https://app.magistry.io/api/v1/tools/propose_discount \
-H "Authorization: Bearer mag_sk_live_…" \
-H "Content-Type: application/json" \
-d '{ "product_ids": ["…"], "discount_percent": 15,
"reason": "Clear winter stock" }'# Claude Code claude mcp add --transport http magistry \ https://app.magistry.io/api/mcp // claude.ai → Settings → Connectors → // Add custom connector → // https://app.magistry.io/api/mcp // OAuth picks your store + scopes on connect.
// scopes
| Scope | Covers | Notes |
|---|---|---|
| read | Every read tool | Bundle — full reporting surface, no writes |
| write | Every write tool | Bundle — implies read; propose_write tools still need approval |
| admin | Everything on your stores, including settings | Bundle — for trusted internal integrations only |
| ads:read · catalog:write · … | One resource, one action | Fine-grained — per resource + action, mix freely per key |
// connect your ai
Add the /api/mcp URL as a custom connector. OAuth walks you through store + scope selection.
app.magistry.io/api/mcp
One command adds the remote server over HTTP — it is in the example on this page.
app.magistry.io/api/mcp
Point Cursor's MCP settings at the remote endpoint and your editor can query the store mid-task.
app.magistry.io/api/mcp
MCP revisions 2026-07-28 and 2025-06-18. OAuth 2.1 with a Client ID Metadata Document, or a Bearer API key.
app.magistry.io/api/mcp
// reference
The full REST surface — every tool, every input schema, every response shape — is published as an OpenAPI document. Point a generator or an agent at it and go.
GET https://app.magistry.io/api/v1/openapi.json
Settings → Developers in the dashboard is where keys live: mint and revoke API keys, pick scopes, browse the full tool catalog with its read / auto_write / propose_write tags, and opt a credential into auto-apply.
// events · versioning
CloudEvents 1.0, signed with ES256 under Standard Webhooks and verifiable against our published JWKS. Delivery is at-least-once: dedupe on the event id. Failed deliveries retry with backoff, and a 410 unsubscribes. Published today: order created and refunded, approval requested, decided and expired, and a field overwritten outside Magistry. Each event type needs the scope that covers it.
POST https://app.magistry.io/api/v1/subscriptions
Version 1 changes additively only. A read never becomes a write, and a scope change counts as breaking. Anything we remove is announced at least 365 days ahead with Deprecation and Sunset headers on the affected calls, and listed in the changelog.
GET https://app.magistry.io/api/v1/changelog.json
https://app.magistry.io/api/v1/openapi.json OpenAPI 3.1, every operation https://app.magistry.io/api/v1/asyncapi.json AsyncAPI 3.0, every event https://app.magistry.io/api/v1/changelog.json changes + deprecations https://app.magistry.io/.well-known/jwks.json webhook + token keys
// developers
One registry powers the dashboard assistant, the MCP server, and the REST API — same scopes, same approval model, same audit trail as everything else in Magistry.
Bearer API keys · OAuth 2.1 + PKCE · Signed webhooks · 365-day deprecation notice
We use cookies to run this site, to see which pages help, and to measure which ads bring people here. You choose per category; everything except the strictly necessary is off until you say otherwise. Cookie policy · Privacy