API Documentation

From a lead to a brand

Audit and check a prospect through the API, then create their brand with POST /v1/projects: the audit becomes its plan and the check its first AI visibility history.

Audit a prospect and check their AI visibility through the API. When they sign, create their brand in your organization with the results already in it, and manage it in Magister from then on.

1. Audit and check the prospect

bash

curl -X POST https://api.magistermarketing.com/v1/audits/site \
  -H "Authorization: Bearer $MAGISTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://acme.com"}'

curl -X POST https://api.magistermarketing.com/v1/ai-visibility/check \
  -H "Authorization: Bearer $MAGISTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"domain": "acme.com"}'

Each answers with a job_id. Keep both; they are billed in API credits like any job.

2. Create the brand when they sign

bash

curl -X POST https://api.magistermarketing.com/v1/projects \
  -H "Authorization: Bearer $MAGISTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"website_url": "https://acme.com", "name": "Acme", "from_jobs": ["<audit job_id>", "<check job_id>"]}'

json

{
  "data": {
    "status": "created",
    "message": "Added Acme. Its marketing plan is being built from the audit you already ran, and its agent is being set up.",
    "project_id": "5b2c1d7e-8a4f-4e2b-9c1d-7e8a4f4e2b9c",
    "name": "Acme",
    "website_url": "https://acme.com/",
    "audit": {
      "job_id": "<audit job_id>",
      "plan_id": "9c1d7e8a-4f4e-4b9c-8d7e-8a4f4e2b9c1d",
      "carried": true
    },
    "ai_visibility": {
      "job_id": "<check job_id>",
      "imported": true,
      "set_id": "1d7e8a4f-4e2b-4c1d-9e8a-4f4e2b9c1d7e",
      "round_id": "7e8a4f4e-2b9c-4d7e-8a4f-4e2b9c1d7e8a",
      "answers": 9
    }
  },
  "credits_charged": 0,
  "request_id": "8f14e45f-ceea-4e7a-9b1c-1f2a3b4c5d6e"
}

The brand is set up as if it had been added in Magister, with its plan, its agent and its place in your billing:

- The audit becomes its plan. No second audit runs. Magister builds the marketing plan from it in a few minutes, billed on your plan's credits like any new brand's first plan, and the audit's AI visibility round carries over with it.

- The check becomes its first AI visibility history. It arrives as a set with the check's questions and engines and one round dated to when the check ran, with every answer, score, mention, position, competitor and source. From then on Magister tracks the set weekly, billed on your plan. An engine that Magister's tracking asks with web search (OpenAI, Claude, Grok) but that your check asked without it is left out, since there is nothing to compare with.

The rules

- from_jobs takes your organization's finished jobs, started by any of its keys: at most one site audit and one AI visibility check, both of the brand's own site.

- A job counts as finished once it reads succeeded: poll GET /v1/jobs/{job_id} with the key that started it (an audit job is settled when it is read), and a job another of your keys started settles by itself within a few minutes. Until then it answers 409 not_ready. A failed job, or a job of another site, answers 422.

- An audit becomes one brand's plan, and a check one brand's history, once: carried into another brand, either answers 409 conflict.

- Sending the same request again never adds a second brand. It answers 200 with the brand it created, with the audit as its plan and the check carried in (once). A brand someone else already added for the site gets nothing carried into it (carried and imported are false, reason brand_exists). A brand's id is returned only when the key's creator can open it; otherwise it answers 409 conflict.

- The key needs the write scope, and its creator must be an owner or admin of the organization, or a member allowed to add brands (403 not_authorized otherwise).

What it costs

Creating the brand costs no API credits. The brand is billed on your plan like any other.

- A brand your plan already includes is created right away, and so is any brand of a paid plan Magister made complimentary.

- Any other brand answers 402 payment_required with its charge (amount_cents, interval) and add_brand_url, and nothing is added or charged: an API key never agrees to a price. Add the brand at add_brand_url instead; the audit and check stay in your API jobs.

- An organization on Free, or with no active plan, answers 402 payment_required with upgrade_url.