01
Mint an API key
In the dashboard, open Settings → Developers and create a key. Scopes are fine-grained per resource and action — start with the read bundle; add write scopes when you need them.
$ mag_sk_live_… # keep it secret~ 1 minute
// developer docs
Build on the spine. Read it first.
The developer surface is small on purpose. A handful of concepts cover 90% of integrations — the rest is calling the same tool registry Otto uses, over REST or MCP, against a decision log you can already inspect. Start here, then go deep.
REST API + MCP server OAuth 2.1 + scoped API keys OpenAPI at /api/v1/openapi.json
// quickstart
Four steps. Ten minutes. First tool call.
The quickstart is built around the read surface — nothing writes to your store until you add write scopes, and even then propose_write keeps a human approval in the loop. You can finish this in your lunch break.
02
Make your first read call
Every capability is a tool — the same registry Otto uses in-app. POST to /api/v1/tools/{tool} with your key; the OpenAPI document at /api/v1/openapi.json lists every tool and shape.
$ curl -X POST …/api/v1/tools/get_store_overview~ 2 minutes
03
Connect your own AI (MCP)
Magistry ships a remote MCP server at /api/mcp. Add it as a custom connector in Claude, or via mcp-remote in Claude Desktop and Cursor — OAuth handles store and scope selection.
$ npx -y mcp-remote https://…/api/mcp~ 3 minutes
04
Write with a safety net
Write tools come in two tiers: auto_write applies immediately, propose_write returns an approval card you confirm in the dashboard. Auto-apply is opt-in, per key, in Settings → Developers.
$ …/api/v1/tools/propose_discount~ 30 seconds
// core concepts
Nine ideas. The rest is composition.
If you can hold these in your head, every Magistry tool call falls into place. Skim them once before you start wiring code.
01
decision_log
The immutable, append-only spine of Magistry. Every action — catalog mutation, ad-budget shift, refund issued, ticket replied — lands as a row with its evidence chain, reversal op, and judge score. Read it like a ledger.
core/auditRead more
02
ALLOWED_TRANSITIONS
The static state-transition map that gates every catalog write. Every SKU lives in exactly one lifecycle state; invalid moves become operator-review rows, not Shopify mutations. Inspect it before you write a custom executor.
core/catalogRead more
03
planner-judge-executor
Every action moves through three roles. Planner drafts the move. Judge scores it 0.0–1.0 against the evidence chain. Executor applies it — only if the judge score clears the threshold for that action type.
core/agentRead more
04
Cost Confidence Tiers
Tier A (verified cost), Tier B (inferred margin), Tier C (orphan). The tier on a SKU decides what the agent is allowed to do — price changes are A-only; copy edits open up at B; archive needs operator confirm at C.
core/safetyRead more
05
Action enum
The full move set the decision_engine can emit. KEEP, SCALE_WINNER, OPTIMIZE_LOSER, DISCOUNT_TEST, DRAFT, VAULT, REVIVE_SEASONAL, FLAG_ORPHAN — each one tied to a trigger, a set of valid from-states, and a pre-stored reversal op.
core/catalogRead more
06
Safety primitives
Kill switch (operator-owned), per-action rate limits, the tier-A discount gate, monthly LLM budget cap, advisory locks, credits metering. The primitives every agent inherits — and the cap you can tune.
core/safetyRead more
07
Marketing Brain
The orchestrator above every agent. Signals in, one context bundle, one decision pass, proposals out — with a weekly strategist for durable initiatives and a reflection loop that turns verified outcomes into lessons.
core/orchestrationRead more
08
Trust ramp
Autonomy is earned per lever. The verdict engine scores every applied action win/loss on a full window; sustained wins promote a lever one tier, a losing streak demotes it immediately. Irreversible moves are never auto-approved.
core/autonomyRead more
09
API + MCP
One tool registry behind Otto, the REST API, and the MCP server. Scoped keys, OAuth 2.1 for MCP clients, and two write tiers — auto_write and propose_write with approval cards in the dashboard.
core/apiRead more
// snippet
Read the log. That's the whole onboarding.
With a key in hand, the first useful call is a read of the store's recent decisions. Everything else — proposing a discount, checking performance, driving your own AI over MCP — composes on top of the same tool registry.
first_call.shcurl
# Read the store's recent decisions — same tools Otto uses
curl -X POST https://app.magistry.io/api/v1/tools/get_recent_decisions \
-H "Authorization: Bearer mag_sk_live_…" \
-H "Content-Type: application/json" \
-d '{ "days": 7 }'
# Every tool + shape is in the OpenAPI document:
# GET https://app.magistry.io/api/v1/openapi.json
# Write tools are tagged: auto_write applies, propose_write
# returns an approval card you confirm in the dashboard. next: connect Claude over MCPread-only by default
// versioning
Continuous delivery, versioned API.
The platform ships continuously — every release is cut automatically from the same pipeline that deploys the product. The API you build against lives in a versioned namespace (/api/v1), so continuous product releases don't break your integration.
How releases ship
- Continuous — features and fixes deploy as they're ready; releases are versioned automatically from the commit history.
- Versioned API — the public surface lives under /api/v1; additive changes only. A breaking change means a new namespace, with overlap.
- Tool registry — new capabilities appear as new tools in the catalog and the OpenAPI document; existing tool shapes stay stable.
Follow what changes
User-facing releases, sourced from the same release pipeline that ships the product — features, fixes, and improvements without internal noise.
The generated spec for /api/v1 — every tool, its input shape, and its read/write tier. Diff it to see exactly what changed between visits.
Live status of the API, dashboard, worker, and agent surfaces — plus incident history when something does go wrong.
// developer docs
Magistry runs your store. We run Magistry.
The REST API and MCP server expose the same tool registry Otto uses in production. Same auth, same rate limits, same audit plane — no shadow surface.
Versioned API · Approval-gated writes · No silent breaking changes