// developer docs

Build on the spine. Read it first.

The Magistry SDK is small on purpose. Six concepts cover 90% of integrations — the rest is composing actions on top of a decision_log you can already inspect. Start here, then go deep.

Open the quickstart

API reference

v1.18.0 stable Python + TypeScript SDKs 6-week release cadence

// quickstart

Four commands. Ten minutes. First decision row.

The quickstart is built around dry-run mode — every step is reversible, nothing reaches Shopify until you promote a row explicitly. If you can install pip, you can finish this in your lunch break.

Install the Magistry CLI

The CLI ships the SDK, the dry-run sandbox, the migration runner, and the decision_log streamer. Python 3.11+ required; no native deps.

$ pip install magistry-sdk

~ 90 seconds

Connect your store

Run `magistry connect shopify` and paste a read-only Admin token. The CLI verifies scopes, samples 50 SKUs, and writes a connection row to your workspace.

$ magistry connect shopify --tier=A

~ 3 minutes

Run your first dry-run

`magistry cycle --dry-run` ships every phase end-to-end without touching Shopify. Output is a decision_log JSON file you can diff against today.

$ magistry cycle --dry-run --agent=catalog

~ 6 minutes

Promote a decision to live

Pick one row from the dry-run output, audit the evidence chain, and promote it. The CLI re-validates ALLOWED_TRANSITIONS and writes back to Shopify.

$ magistry promote --row=dec_01J9X2…

~ 30 seconds

// core concepts

Six ideas. The rest is composition.

If you can hold these six in your head, every Magistry endpoint and SDK call falls into place. Skim them once before you start wiring code.

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

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

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

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

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

Safety primitives

Kill switch (default-on), per-action rate limits, tier-of-evidence gates, trademark filter, uniqueness check, LLM budget caps, advisory locks. The seven primitives every agent inherits — and the four flags you can tune.

core/safetyRead more

// snippet

Read the log. That's the whole onboarding.

Once the SDK is installed, the first useful program is a stream of the decision_log. Everything else — promoting a row, gating an action, replaying a chargeback — composes on top of this loop.

stream_decisions.pypython 3.11+

# Stream the last 24h of catalog decisions for a store
from magistry import Magistry

client = Magistry(
    api_key="sk_live_…",                # workspace key
    store_id="stk_2YHFZ3WkP6e3xL2",     # store handle
)

# decision_log is append-only — pagination is by created_at
for row in client.decisions.stream(
    agent="catalog",
    since="2026-05-24T00:00:00Z",
    limit=200,
):
    print(row.action, row.subject, row.judge_score)

next: promote a row to liveworks in dry-run

// versioning + release cadence

One version. Shipped on a calendar.

The SDK, the worker, the REST API, and the docs ship together on a six-week train. Patch releases land in-between for security and clock-skew fixes. Breaking changes are batched, dated, and live in a separate v-prefixed namespace for a full year before the old shape is removed.

Release train

Minor release — every six weeks, on a Tuesday at 10:00 UTC. Backwards-compatible.
Patch release — as needed for security, clock-skew, or vendor-API regressions. Auto-applied to managed workers.
Major release — once a year. New namespace (e.g. /v2), 12-month overlap with the previous one before deprecation.

Recent releases

v1.18.0Stable2026-05-21
Researcher gains Pinterest-trend lane, Catalog gains a per-collection ROAS floor override, and decision_log adds a `parent_id` field for cycle ancestry.
v1.17.2Stable2026-05-07
Patch: tightened HMAC-SHA256 webhook clock skew to ±5 minutes, fixed an off-by-one in dayparting windows across DST boundaries.
v1.17.0Stable2026-04-23
Disputes opens GA — full Ethoca + Verifi + Visa RDR integration, with replay-from-evidence on every chargeback row.

// developer docs

Magistry runs your store. We run Magistry.

The SDK is the same one our worker uses in production. Same auth, same rate limits, same audit plane — no shadow surface.

See it in action

API reference

Stable for a year · Versioned changelogs · No silent breaking changes