API Documentation

Introduction

Welcome to the Magister API. Run Magister's AI visibility checks, full marketing and AEO audits, keyword research, brand profiles, page speed, search competitors and site maps for any domain, from your own code over HTTPS and JSON.

Quick start

Get an API key and 300 free credits, then make your first call in a minute. Read the Quickstart

bash

export MAGISTER_API_KEY=mm_live_...

# Your API credit balance (free)
curl https://api.magistermarketing.com/v1/credits \
  -H "Authorization: Bearer $MAGISTER_API_KEY"

# Start an AI visibility check: a job, answered 202 with its job_id
curl https://api.magistermarketing.com/v1/ai-visibility/check \
  -H "Authorization: Bearer $MAGISTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "max_credits": 75}'

# Poll it until "status" is no longer "running"
curl https://api.magistermarketing.com/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $MAGISTER_API_KEY"

API authentication

Every request needs an API key. Send it in the Authorization: Bearer mm_live_… header to https://api.magistermarketing.com. A key is read-only or full, and can have a daily credit cap.

No key yet? Create one in Settings → Developers → API keys, or sign up for the API. Keep keys on a server, never in a web page.

Limits

60 requests a minute and 5 running jobs per organization, and a key's own daily cap if it has one. Over a limit the API answers 429 with Retry-After.

What the API does

AI visibility for any domain

11 AI engines asked the questions a buyer would: ChatGPT, Gemini and Google AI Mode as a buyer sees them, and the makers' models with or without web search. A domain in, a scored result out, with no brand to set up.

Every answer, in full

Each answer with its sources, the competitors named beside you, sentiment, and the score and its parts. Every finished job has an HTML report and a share link.

Pay per call, apart from any plan

Prepaid API credits at $0.02 each. Every JSON result says what it cost (credits_charged), and max_credits refuses a job that could cost more before it starts.

Jobs and signed webhooks

Checks and audits run as jobs: poll them, or pass a webhook_url and get a signed callback, retried over a day. Reports are shareable for 30 days.

Endpoints

AI visibility

Where a brand stands in ChatGPT, Gemini, Claude and 8 more.

Audits

A whole site's marketing, or one page's AI readiness.

Search

What people search for, and who ranks beside you.

Site and brand

A site's brand, speed and pages.

Account and jobs

Your balance, your brands, and the jobs you started.

Other ways in

Your AI agent

Copy for your AI hands Claude Code, Cursor, Codex or ChatGPT every page of these docs as Markdown, to build the integration from.

The whole reference as Markdown

OpenAPI

The OpenAPI document behind every page here, for generating a client or importing into Postman.

openapi.json

MCP for assistants

Working in an assistant rather than in code? Connect Magister's MCP server: https://mcp.magistermarketing.com/mcp

Set up MCP

Reading these docs with an AI

Copy for your AI (above) gives your agent the address of every page as Markdown; paste it into Claude Code, Cursor, Codex or ChatGPT and the agent reads the pages itself.
Copy as Markdown hands over the whole reference at once, for an agent that cannot open links. Every endpoint page has its own Markdown and its own Copy for AI.
llms.txt indexes every Magister doc, and /docs/api.md is this whole reference in one file.

Response codes

200	Success: a JSON result with `credits_charged` (the job report is HTML).
202	A job started: poll `GET /v1/jobs/{job_id}` until `status` is no longer `running`, or wait for its webhook.
401	Missing, unknown or revoked API key.
402	Not enough API credits (`limit_reached`, `credits_exhausted`, with `top_up_url`), over `max_credits`, or a hold above the key's whole daily cap (`key_daily_cap_too_low`).
403	The key lacks a scope, or the endpoint is not enabled.
404	Unknown job; or the API is not enabled.
409	Not ready yet: the report of a job that has not finished.
422	Invalid input (`validation_error`, with `fields` when the body does not fit the schema).
429	60 requests a minute or 5 running jobs per organization, or the key's daily cap; see `Retry-After`.
500	The request failed unexpectedly (`upstream_failed`): retryable when it failed before it started; after, `retryable` is false and the error carries its `request_id`.
502	An upstream provider failed. Billed only what it used before failing.
503	The request could not start (`transport_unavailable`).

Errors are JSON with error, message and retryable; retry only when it is true. Every error code

A question, or something that looks wrong? Contact support.