# Magistry

> Magistry is an autonomous operations platform for Shopify stores and standard tenants: it reads a merchant's catalogue, ads, orders, feed and customer service, decides what to change, and executes inside published guardrails. Everything the in-app operator can do is also available over a REST API and a remote MCP server, behind OAuth 2.1 or an API key.

The programmable surface is **116 operations** (66 read, 50 write) on API version 1, each requiring exactly one scope. The documents below are generated from the same registry that serves the requests, so they cannot describe a surface that does not exist. All of them are public and unauthenticated, and all of them carry contract only — no merchant data is reachable without a credential.

## API contract

- [OpenAPI 3.1 specification](https://app.magistry.io/api/v1/openapi.json): every operation, its request schema, its required scope and every error code. Generated from the tool registry.
- [AsyncAPI specification](https://app.magistry.io/api/v1/asyncapi.json): the outbound event contract for webhook subscriptions.
- [Changelog and deprecations](https://app.magistry.io/api/v1/changelog.json): machine-readable support policy — a 365-day minimum notice, additive-only within a major version, and every announced deprecation with its sunset date and its replacement.

## Model Context Protocol

- [MCP server discovery](https://app.magistry.io/api/mcp): a GET returns the server name, the supported protocol revisions (2026-07-28, 2025-06-18) and where to authorize. The same URL is the JSON-RPC endpoint for a POST carrying a bearer token.
- [MCP registry manifest](https://www.magistry.io/server.json): this server in the `server.json` format the official MCP registry publishes, for a client that wants to install it without being handed the address.
- [Protected resource metadata](https://app.magistry.io/.well-known/oauth-protected-resource): RFC 9728 — which authorization server guards the MCP endpoint, and the scopes it understands.
- [Authorization server metadata](https://app.magistry.io/.well-known/oauth-authorization-server): RFC 8414 — the authorize, token, revoke and introspection endpoints.

## Authorization

- [Scopes](https://app.magistry.io/api/v1/openapi.json): 27 capability scopes — two broad bundles (`read`, `write`), a `resource:action` pair per capability area, and `admin`. A token is evaluated against exactly one required scope per operation and nothing else. `offline_access` is granted alongside them to opt into a refresh token; it gates no operation.
- An OAuth client may be registered dynamically, or identified by a Client ID Metadata Document — an https URL serving your client metadata, passed as `client_id`. Dynamic registration is deprecated with notice; the changelog above carries the date.
- [Error codes](https://app.magistry.io/docs/api/errors): every code, what it means, what to do about it, and whether a retry is reasonable. Public — checked with an unauthenticated fetch, because it lives on the app origin and almost everything else there needs a login.

## Product and policy

- [What Magistry does](https://www.magistry.io/platform): the agents, what each one decides, and where a merchant sees it.
- [Pricing](https://www.magistry.io/pricing): plans, included credits and overage.
- [Integrations](https://www.magistry.io/integrations): the platforms Magistry reads and writes.
- [Trust and sub-processors](https://www.magistry.io/company/trust): where data goes and who processes it.
- [Privacy notice](https://www.magistry.io/legal/privacy)
- [Data processing agreement](https://www.magistry.io/legal/dpa)
- [Terms of service](https://www.magistry.io/legal/terms)

## Optional

- [Blog feed](https://www.magistry.io/feed.xml): product and engineering writing.
- [Sitemap](https://www.magistry.io/sitemap.xml)

## Notes for an agent reading this

- Every call is authenticated. There is no anonymous read of merchant data anywhere on this platform; the documents above are contract, not content.
- Errors carry a stable machine-readable `error` code and a `request_id`. Branch on the code — there are 20 of them and they are enumerated in the OpenAPI document — never on the prose.
- Write operations accept an idempotency key. `idempotency_in_flight` means ask again; `idempotency_unavailable` means nothing was written. Those two are the pair worth telling apart before you retry.
- This file is generated from the API surface itself (`apps/dashboard/lib/api/artifacts/llms-txt.ts`). If a number here disagrees with the OpenAPI document, the OpenAPI document is right and our CI is broken.