// developers · rest

Every operation, with what it needs and what it may do.

188 operations: 106 read, 48 automatic write, 34 proposed write. Each one is a POST with a JSON body, described in the OpenAPI document with the scope it needs and the risk tier that decides whether it applies or waits for approval.

// call

A read and a proposed write.

read · orders:read

curl -X POST https://app.magistry.io/api/v1/tools/get_orders \
  -H "Authorization: Bearer mag_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "window_days": 7, "limit": 20 }'

proposed write · catalog:write

curl -X POST https://app.magistry.io/api/v1/tools/shopify_update_variant_price \
  -H "Authorization: Bearer mag_sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reprice-2026-10-20-001" \
  -d '{ "shopify_variant_id": "gid://shopify/ProductVariant/…", "new_price": 34.95 }'

A proposed write returns an approval card instead of changing the store. Send an Idempotency-Key header (or an idempotency_key argument) on any write so a retry after a timeout cannot apply twice. The full schemas live in the OpenAPI document:

openapi

curl https://app.magistry.io/api/v1/openapi.json

// tiers

Three risk tiers.

Tier	Operations	What happens
read	106	Answers and changes nothing.
automatic write	48	Applies when the credential carries the write scope.
proposed write	34	Creates an approval card. Nothing changes until a person approves it in Magistry.

// for apps

Intent, approvals and simulation.

These operations exist for connected apps rather than scripts, so they take an OAuth token and refuse an API key.

Declare intent

State what a field should be and let Magistry reconcile it. One owner per field: a second app declaring the same field is refused, not raced. Fields that can be declared today:

Variants: price (catalog:write)
Variants: compare_at_price (catalog:write)
Ad campaigns: status (ads:write)
Ad campaigns: daily_budget (ads:write)
Ad campaigns: bidding (ads:write)

Ask a person

POST /api/v1/approvals puts an action your app wants to take in front of the merchant as an approval card. Poll /api/v1/approvals/status or subscribe to approval.decided.

POST /api/v1/simulate runs an action through the store’s own rules, ownership and spend ceilings inside a transaction that is always rolled back, and returns what each gate would decide.

intent

curl -X POST https://app.magistry.io/api/v1/intent \
  -H "Authorization: Bearer <oauth access token>" \
  -H "Content-Type: application/json" \
  -d '{ "resource_kind": "campaign", "resource_ref": "…",
        "field": "daily_budget", "desired": 80,
        "reason": "Weekend sale", "expires_at": "2026-10-27T00:00:00Z" }'

approval

curl -X POST https://app.magistry.io/api/v1/approvals \
  -H "Authorization: Bearer <oauth access token>" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Reorder 400 units from the usual supplier",
        "amount_cents": 520000, "currency": "EUR",
        "reversibility_class": "compensatable",
        "idempotency_key": "po-8812" }'

simulate

curl -X POST https://app.magistry.io/api/v1/simulate \
  -H "Authorization: Bearer <oauth access token>" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "ads_google", "action": "adjust_budget",
        "facts": { "budget_change_pct": 20 } }'

// reference

All 188 operations.

Grouped by the resource their scope names. Generated from the API's contract snapshot at build time.

creative34 operations ›

Operation	Path	Scope	Tier
`list_designs`	POST /api/v1/tools/list_designs	creative:read	read
`read_design`	POST /api/v1/tools/read_design	creative:read	read
`get_design_request`	POST /api/v1/tools/get_design_request	creative:read	read
`get_brand_kit`	POST /api/v1/tools/get_brand_kit	creative:read	read
`update_brand_kit`	POST /api/v1/tools/update_brand_kit	creative:write	automatic write
`read_brand_from_website`	POST /api/v1/tools/read_brand_from_website	creative:write	automatic write
`check_design`	POST /api/v1/tools/check_design	creative:read	read
`create_design`	POST /api/v1/tools/create_design	creative:write	automatic write
`compose_design`	POST /api/v1/tools/compose_design	creative:write	automatic write
`create_campaign_set`	POST /api/v1/tools/create_campaign_set	creative:write	automatic write
`edit_design`	POST /api/v1/tools/edit_design	creative:write	automatic write
`vary_design`	POST /api/v1/tools/vary_design	creative:write	automatic write
`translate_design`	POST /api/v1/tools/translate_design	creative:write	automatic write
`use_design_variation`	POST /api/v1/tools/use_design_variation	creative:write	automatic write
`add_design_music`	POST /api/v1/tools/add_design_music	creative:write	automatic write
`list_design_audio`	POST /api/v1/tools/list_design_audio	creative:read	read
`set_design_audio`	POST /api/v1/tools/set_design_audio	creative:write	automatic write
`list_design_timeline`	POST /api/v1/tools/list_design_timeline	creative:read	read
`set_design_transition`	POST /api/v1/tools/set_design_transition	creative:write	automatic write
`set_design_sfx`	POST /api/v1/tools/set_design_sfx	creative:write	automatic write
`export_design`	POST /api/v1/tools/export_design	creative:write	automatic write
`propose_design_post`	POST /api/v1/tools/propose_design_post	creative:write	automatic write
`list_design_ad_campaigns`	POST /api/v1/tools/list_design_ad_campaigns	creative:read	read
`propose_design_ad`	POST /api/v1/tools/propose_design_ad	creative:write	automatic write
`list_design_comments`	POST /api/v1/tools/list_design_comments	creative:read	read
`comment_on_design`	POST /api/v1/tools/comment_on_design	creative:write	automatic write
`resolve_design_comment`	POST /api/v1/tools/resolve_design_comment	creative:write	automatic write
`fix_design_comment`	POST /api/v1/tools/fix_design_comment	creative:write	automatic write
`fill_design_for_locations`	POST /api/v1/tools/fill_design_for_locations	creative:write	automatic write
`get_design_activity`	POST /api/v1/tools/get_design_activity	creative:read	read
`bind_design_data`	POST /api/v1/tools/bind_design_data	creative:write	automatic write
`list_quotable_reviews`	POST /api/v1/tools/list_quotable_reviews	creative:read	read
`get_design_results`	POST /api/v1/tools/get_design_results	creative:read	read
`refresh_design_data`	POST /api/v1/tools/refresh_design_data	creative:write	automatic write

automation33 operations ›

Operation	Path	Scope	Tier
`get_recent_decisions`	POST /api/v1/tools/get_recent_decisions	automation:read	read
`get_alerts`	POST /api/v1/tools/get_alerts	automation:read	read
`get_job_runs`	POST /api/v1/tools/get_job_runs	automation:read	read
`create_alert`	POST /api/v1/tools/create_alert	automation:write	automatic write
`list_automations`	POST /api/v1/tools/list_automations	automation:read	read
`disable_automation`	POST /api/v1/tools/disable_automation	automation:write	automatic write
`compile_workflow_from_nl`	POST /api/v1/tools/compile_workflow_from_nl	automation:write	proposed write
`enable_automation`	POST /api/v1/tools/enable_automation	automation:write	automatic write
`run_calibration`	POST /api/v1/tools/run_calibration	automation:write	automatic write
`run_classification`	POST /api/v1/tools/run_classification	automation:write	automatic write
`run_decide_dry`	POST /api/v1/tools/run_decide_dry	automation:write	automatic write
`run_sync_catalog`	POST /api/v1/tools/run_sync_catalog	automation:write	automatic write
`run_sync_orders`	POST /api/v1/tools/run_sync_orders	automation:write	automatic write
`run_embeddings`	POST /api/v1/tools/run_embeddings	automation:write	automatic write
`run_anomaly_check`	POST /api/v1/tools/run_anomaly_check	automation:write	automatic write
`run_supplier_health`	POST /api/v1/tools/run_supplier_health	automation:write	automatic write
`run_cannibalization`	POST /api/v1/tools/run_cannibalization	automation:write	automatic write
`run_research`	POST /api/v1/tools/run_research	automation:write	automatic write
`run_ab_resolve`	POST /api/v1/tools/run_ab_resolve	automation:write	automatic write
`save_skill`	POST /api/v1/tools/save_skill	automation:write	automatic write
`list_skills`	POST /api/v1/tools/list_skills	automation:read	read
`delete_skill`	POST /api/v1/tools/delete_skill	automation:write	automatic write
`approval_submit`	POST /api/v1/approvals	automation:write	automatic write
`approval_status`	POST /api/v1/approvals/status	automation:read	read
`approval_list`	POST /api/v1/approvals/list	automation:read	read
`approval_withdraw`	POST /api/v1/approvals/withdraw	automation:write	automatic write
`simulate`	POST /api/v1/simulate	automation:read	read
`policy_list`	POST /api/v1/policies/list	automation:read	read
`policy_create`	POST /api/v1/policies	automation:write	automatic write
`policy_update`	POST /api/v1/policies/update	automation:write	automatic write
`policy_delete`	POST /api/v1/policies/delete	automation:write	automatic write
`receipts_list`	POST /api/v1/receipts	automation:read	read
`receipts_price_memory`	POST /api/v1/receipts/price	automation:read	read

general20 operations ›

Operation	Path	Scope	Tier
`list_store_actions`	POST /api/v1/tools/list_store_actions	read	read
`where_in_magistry`	POST /api/v1/tools/where_in_magistry	read	read
`get_site_overview`	POST /api/v1/tools/get_site_overview	read	read
`get_organic_search`	POST /api/v1/tools/get_organic_search	read	read
`ask_user_question`	POST /api/v1/tools/ask_user_question	read	read
`render_chart`	POST /api/v1/tools/render_chart	read	read
`show_metrics`	POST /api/v1/tools/show_metrics	read	read
`create_artifact`	POST /api/v1/tools/create_artifact	read	read
`update_artifact`	POST /api/v1/tools/update_artifact	read	read
`get_chatgpt_ads_authority`	POST /api/v1/tools/get_chatgpt_ads_authority	read	read
`get_brain_thinking`	POST /api/v1/tools/get_brain_thinking	read	read
`tell_brain`	POST /api/v1/tools/tell_brain	write	automatic write
`provisioning_status`	POST /api/v1/provisioning/status	read	read
`provisioning_start`	POST /api/v1/provisioning/start	write	proposed write
`provisioning_cancel`	POST /api/v1/provisioning/cancel	write	automatic write
`intent_declare`	POST /api/v1/intent	write	proposed write
`intent_status`	POST /api/v1/intent/status	read	read
`intent_list`	POST /api/v1/intent/list	read	read
`intent_release`	POST /api/v1/intent/release	write	automatic write
`intent_revert`	POST /api/v1/intent/revert	write	automatic write

catalog19 operations ›

Operation	Path	Scope	Tier
`get_store_overview`	POST /api/v1/tools/get_store_overview	catalog:read	read
`query_products`	POST /api/v1/tools/query_products	catalog:read	read
`get_calibration`	POST /api/v1/tools/get_calibration	catalog:read	read
`get_variants`	POST /api/v1/tools/get_variants	catalog:read	read
`get_content_versions`	POST /api/v1/tools/get_content_versions	catalog:read	read
`get_product_detail`	POST /api/v1/tools/get_product_detail	catalog:read	read
`find_similar_products`	POST /api/v1/tools/find_similar_products	catalog:read	read
`get_ai_readiness`	POST /api/v1/tools/get_ai_readiness	catalog:read	read
`get_ai_repairs`	POST /api/v1/tools/get_ai_repairs	catalog:read	read
`propose_state_transition`	POST /api/v1/tools/propose_state_transition	catalog:write	proposed write
`propose_draft`	POST /api/v1/tools/propose_draft	catalog:write	proposed write
`shopify_get_shop_profile`	POST /api/v1/tools/shopify_get_shop_profile	catalog:read	read
`shopify_list_markets`	POST /api/v1/tools/shopify_list_markets	catalog:read	read
`shopify_set_product_status`	POST /api/v1/tools/shopify_set_product_status	catalog:write	proposed write
`shopify_update_variant_price`	POST /api/v1/tools/shopify_update_variant_price	catalog:write	proposed write
`shopify_update_inventory`	POST /api/v1/tools/shopify_update_inventory	catalog:write	proposed write
`shopify_update_tags`	POST /api/v1/tools/shopify_update_tags	catalog:write	proposed write
`shopify_set_metafield`	POST /api/v1/tools/shopify_set_metafield	catalog:write	proposed write
`shopify_update_content`	POST /api/v1/tools/shopify_update_content	catalog:write	proposed write

ads15 operations ›

Operation	Path	Scope	Tier
`get_ad_performance`	POST /api/v1/tools/get_ad_performance	ads:read	read
`get_marketing_brain`	POST /api/v1/tools/get_marketing_brain	ads:read	read
`get_competitor_ad_intel`	POST /api/v1/tools/get_competitor_ad_intel	ads:read	read
`get_ad_campaigns`	POST /api/v1/tools/get_ad_campaigns	ads:read	read
`ads_run_gaql`	POST /api/v1/tools/ads_run_gaql	ads:read	read
`ads_list_accessible_customers`	POST /api/v1/tools/ads_list_accessible_customers	ads:read	read
`ads_set_campaign_status`	POST /api/v1/tools/ads_set_campaign_status	ads:write	proposed write
`ads_set_campaign_budget`	POST /api/v1/tools/ads_set_campaign_budget	ads:write	proposed write
`ads_add_negative_keywords`	POST /api/v1/tools/ads_add_negative_keywords	ads:write	proposed write
`ads_create_campaign`	POST /api/v1/tools/ads_create_campaign	ads:write	proposed write
`meta_run_insights`	POST /api/v1/tools/meta_run_insights	ads:read	read
`meta_get_ad_entities`	POST /api/v1/tools/meta_get_ad_entities	ads:read	read
`meta_get_audiences`	POST /api/v1/tools/meta_get_audiences	ads:read	read
`meta_create_campaign`	POST /api/v1/tools/meta_create_campaign	ads:write	proposed write
`meta_sync_audiences`	POST /api/v1/tools/meta_sync_audiences	ads:write	proposed write

finance15 operations ›

Operation	Path	Scope	Tier
`finance_entities_list`	POST /api/v1/finance/entities	finance:read	read
`finance_accounts_list`	POST /api/v1/finance/accounts	finance:read	read
`finance_periods_list`	POST /api/v1/finance/periods	finance:read	read
`finance_journal_entries_list`	POST /api/v1/finance/journal-entries	finance:read	read
`finance_bank_accounts_list`	POST /api/v1/finance/bank-accounts	finance:read	read
`finance_einvoice_messages_list`	POST /api/v1/finance/einvoice-messages	finance:read	read
`finance_bank_transactions_list`	POST /api/v1/finance/bank-transactions	finance:read	read
`finance_trial_balance`	POST /api/v1/finance/reports/trial-balance	finance:read	read
`finance_profit_and_loss`	POST /api/v1/finance/reports/profit-and-loss	finance:read	read
`finance_balance_sheet`	POST /api/v1/finance/reports/balance-sheet	finance:read	read
`finance_changes`	POST /api/v1/finance/changes	finance:read	read
`finance_proposals_list`	POST /api/v1/finance/proposals	finance:read	read
`finance_export_create`	POST /api/v1/finance/exports	finance:read	read
`finance_export_status`	POST /api/v1/finance/exports/status	finance:read	read
`finance_export_download`	POST /api/v1/finance/exports/download	finance:read	read

analytics12 operations ›

Operation	Path	Scope	Tier
`query_performance`	POST /api/v1/tools/query_performance	analytics:read	read
`compare_periods`	POST /api/v1/tools/compare_periods	analytics:read	read
`query_cannibalization`	POST /api/v1/tools/query_cannibalization	analytics:read	read
`get_ai_referred_orders`	POST /api/v1/tools/get_ai_referred_orders	analytics:read	read
`ga4_get_admin_config`	POST /api/v1/tools/ga4_get_admin_config	analytics:read	read
`ga4_list_audiences`	POST /api/v1/tools/ga4_list_audiences	analytics:read	read
`ga4_list_data_streams`	POST /api/v1/tools/ga4_list_data_streams	analytics:read	read
`ga4_run_report`	POST /api/v1/tools/ga4_run_report	analytics:read	read
`ga4_channel_performance`	POST /api/v1/tools/ga4_channel_performance	analytics:read	read
`ga4_buyer_demographics`	POST /api/v1/tools/ga4_buyer_demographics	analytics:read	read
`ga4_set_data_retention`	POST /api/v1/tools/ga4_set_data_retention	analytics:write	proposed write
`ga4_create_audience`	POST /api/v1/tools/ga4_create_audience	analytics:write	proposed write

costs7 operations ›

Operation	Path	Scope	Tier
`get_product_costs`	POST /api/v1/tools/get_product_costs	costs:read	read
`get_expenses`	POST /api/v1/tools/get_expenses	costs:read	read
`inspect_expense_import`	POST /api/v1/tools/inspect_expense_import	costs:read	read
`propose_expense_import`	POST /api/v1/tools/propose_expense_import	costs:write	proposed write
`inspect_cost_import`	POST /api/v1/tools/inspect_cost_import	costs:read	read
`propose_cost_import`	POST /api/v1/tools/propose_cost_import	costs:write	proposed write
`shopify_update_variant_cost`	POST /api/v1/tools/shopify_update_variant_cost	costs:write	proposed write

admin6 operations ›

Operation	Path	Scope	Tier
`cross_store_link_status`	POST /api/v1/tools/cross_store_link_status	admin:read	read
`propose_cross_store_link`	POST /api/v1/tools/propose_cross_store_link	admin:write	proposed write
`shopify_graphql_query`	POST /api/v1/tools/shopify_graphql_query	admin:read	read
`get_store_settings`	POST /api/v1/tools/get_store_settings	admin:read	read
`set_kill_switch`	POST /api/v1/tools/set_kill_switch	admin:write	proposed write
`set_automation_enabled`	POST /api/v1/tools/set_automation_enabled	admin:write	proposed write

cs6 operations ›

Operation	Path	Scope	Tier
`get_cs_attention`	POST /api/v1/tools/get_cs_attention	cs:read	read
`get_cs_threads`	POST /api/v1/tools/get_cs_threads	cs:read	read
`get_cs_thread`	POST /api/v1/tools/get_cs_thread	cs:read	read
`cs_send_reply`	POST /api/v1/tools/cs_send_reply	cs:write	proposed write
`cs_triage_thread`	POST /api/v1/tools/cs_triage_thread	cs:write	automatic write
`cs_copilot_ask`	POST /api/v1/tools/cs_copilot_ask	cs:read	read

merchant5 operations ›

Operation	Path	Scope	Tier
`merchant_get_account_issues`	POST /api/v1/tools/merchant_get_account_issues	merchant:read	read
`merchant_get_product_views`	POST /api/v1/tools/merchant_get_product_views	merchant:read	read
`merchant_run_report`	POST /api/v1/tools/merchant_run_report	merchant:read	read
`merchant_upsert_supplemental_labels`	POST /api/v1/tools/merchant_upsert_supplemental_labels	merchant:write	proposed write
`merchant_delete_supplemental_labels`	POST /api/v1/tools/merchant_delete_supplemental_labels	merchant:write	proposed write

orders5 operations ›

Operation	Path	Scope	Tier
`get_orders_summary`	POST /api/v1/tools/get_orders_summary	orders:read	read
`get_orders`	POST /api/v1/tools/get_orders	orders:read	read
`shopify_create_refund`	POST /api/v1/tools/shopify_create_refund	orders:write	proposed write
`shopify_cancel_order`	POST /api/v1/tools/shopify_cancel_order	orders:write	proposed write
`shopify_update_shipping_address`	POST /api/v1/tools/shopify_update_shipping_address	orders:write	proposed write

promotions5 operations ›

Operation	Path	Scope	Tier
`get_discount_history`	POST /api/v1/tools/get_discount_history	promotions:read	read
`get_promotion_detail`	POST /api/v1/tools/get_promotion_detail	promotions:read	read
`propose_discount`	POST /api/v1/tools/propose_discount	promotions:write	proposed write
`shopify_create_discount_code`	POST /api/v1/tools/shopify_create_discount_code	promotions:write	proposed write
`shopify_create_gift_card`	POST /api/v1/tools/shopify_create_gift_card	promotions:write	proposed write

research4 operations ›

Operation	Path	Scope	Tier
`get_research_candidates`	POST /api/v1/tools/get_research_candidates	research:read	read
`lookup_domain_research`	POST /api/v1/tools/lookup_domain_research	research:read	read
`web_read`	POST /api/v1/tools/web_read	research:read	read
`web_search`	POST /api/v1/tools/web_search	research:read	read

disputes1 operation ›

Operation	Path	Scope	Tier
`get_disputes`	POST /api/v1/tools/get_disputes	disputes:read	read

reputation1 operation ›

Operation	Path	Scope	Tier
`get_reviews`	POST /api/v1/tools/get_reviews	reputation:read	read

Build on the same tools the product uses.

Create a sandbox key on demo data, or start free and connect a real store.

Start free

Read the OpenAPI document

MCP + REST · OAuth 2.1 or API keys · every call audited