Magister API
API ReferenceHelp Center

API Documentation

Examples

Markdown

Real requests and responses for the AI visibility check, keyword research, competitors, page speed and the full audit, with how long each took and what it cost: ready to paste into an LLM or a coding agent.

Each example is a real run against tally.so, trimmed to a few items per list, with long answers cut short here (…); the API returns each answer whole. Your figures differ: answers change from run to run, and credits are measured per run.

The engines a check can ask (free)

bash
curl -X GET https://api.magistermarketing.com/v1/ai-visibility/engines \
  -H "Authorization: Bearer $MAGISTER_API_KEY"

One engine of the list:

json
{
  "name": "chatgpt",
  "label": "ChatGPT",
  "web_search": "always",
  "answered_by": "The ChatGPT app, read through DataForSEO",
  "default": true,
  "available": true,
  "typical_credits_per_answer": 1.2,
  "max_credits_per_answer": 2.5
}

An AI visibility check (a job)

bash
curl -X POST https://api.magistermarketing.com/v1/ai-visibility/check \
  -H "Authorization: Bearer $MAGISTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"tally.so","engines":["chatgpt","gemini","claude","perplexity","openai"]}'

This one names the 5 engines it asked; with only a domain, a check asks the 3 default engines. It answers 202 with a job_id; poll GET /v1/jobs/{job_id} (or pass webhook_url). This one took 1 min 5 s. Every answer comes back whole, with its sources.

bash
curl -X GET https://api.magistermarketing.com/v1/jobs/cc838f9f-4f8c-4c1a-9cb1-e9835e78cbe5 \
  -H "Authorization: Bearer $MAGISTER_API_KEY"
json
{
  "job_id": "cc838f9f-4f8c-4c1a-9cb1-e9835e78cbe5",
  "kind": "ai_visibility_check",
  "status": "succeeded",
  "created_at": "2026-11-11T21:40:21.622813+00:00",
  "finished_at": "2026-11-11T21:41:26.877514+00:00",
  "credits_charged": 24.75,
  "result": {
    "domain": "tally.so",
    "brand_name": "Tally Forms",
    "score": 48,
    "mention_rate": 67,
    "citation_rate": 40,
    "average_position": 2.2,
    "answers": 15,
    "failed_answers": 0,
    "engines": [
      "chatgpt",
      "gemini",
      "claude",
      "perplexity",
      "openai"
    ],
    "by_engine": {
      "chatgpt": {
        "model": null,
        "score": 52,
        "answers": 3,
        "grounding": "live_search",
        "sentiment": {
          "neutral": 1,
          "negative": 0,
          "positive": 2
        },
        "web_search": true,
        "mention_rate": 100,
        "citation_rate": 67,
        "average_position": 2.7
      },
      "claude": {
        "model": "claude-haiku-5-5",
        "score": 54,
        "answers": 3,
        "grounding": "live_search",
        "sentiment": {
          "neutral": 0,
          "negative": 0,
          "positive": 2
        },
        "web_search": true,
        "mention_rate": 67,
        "citation_rate": 33,
        "average_position": 2
      }
    },
    "results": [
      {
        "cited": true,
        "model": null,
        "score": 71,
        "answer": "For a small business, I'd prioritize form builders that offer **free submissions, professional-looking forms, customer lead collection, conditional logic, and integrations** without forcing you to upgrade immediately.\n\nI've compared the strongest options available in November 2026. These are my top recommendations.\n\n# Best free form builders for small businesses\n\n\n\n\n\n(Best overall)\n\n**1\\.…",
        "engine": "chatgpt",
        "prompt": "Best free form builders for small businesses",
        "status": "ready",
        "branded": false,
        "seconds": 31.7,
        "named_as": null,
        "position": 1,
        "citations": [
          {
            "url": "https://tally.so/",
            "title": "Visit Tally",
            "domain": "tally.so",
            "snippet": null,
            "own_site": true
          },
          {
            "url": "https://forms.google.com/",
            "title": "Visit Google Forms",
            "domain": "google.com",
            "snippet": null,
            "own_site": false
          },
          {
            "url": "https://fillout.com/",
            "title": "Visit Fillout",
            "domain": "fillout.com",
            "snippet": null,
            "own_site": false
          }
        ],
        "mentioned": true,
        "sentiment": "positive",
        "web_search": true,
        "prompt_type": "pricing",
        "score_parts": {
          "depth": {
            "max": 15,
            "score": 15
          },
          "framing": {
            "max": 15,
            "score": 15
          },
          "accuracy": {
            "max": 5,
            "score": 5
          },
          "citation": {
            "max": 10,
            "score": 10
          },
          "visibility": {
            "max": 25,
            "score": 6
          },
          "competitive": {
            "max": 10,
            "score": 7
          },
          "recommendation": {
            "max": 20,
            "score": 13
          }
        },
        "brands_named": [
          "Fillout",
          "Stripe",
          "HubSpot Forms",
          "HubSpot",
          "Zoho Forms"
        ],
        "judge_reason": "Tally is the top-ranked, strongly praised choice, with specific features and a generous-free-plan recommendation alongside several other form builders.",
        "competitors_found": [],
        "competitors_named": [
          "Fillout",
          "HubSpot Forms",
          "Zoho Forms"
        ]
      },
      {
        "cited": true,
        "model": "claude-haiku-5-5",
        "score": 97,
        "answer": "Here are the strongest free options for small businesses in 2026. Most of the comparison sites that ranked these are run by form vendors, so check current limits on each pricing page before committing.\n\n1. **Tally (best overall for most small businesses).** One review says Tally is the best free form builder for small businesses because it has no form or response limits and includes payments,…",
        "engine": "claude",
        "prompt": "Best free form builders for small businesses",
        "status": "ready",
        "branded": false,
        "seconds": 19.3,
        "named_as": null,
        "position": 1,
        "citations": [
          {
            "url": "https://paperform.co/form-builders/best-form-builders-for-small-businesses/",
            "title": "Best Form Builders for Small Businesses in 2026",
            "domain": "paperform.co",
            "snippet": null,
            "own_site": false
          },
          {
            "url": "https://tally.so/help/best-free-online-form-builders",
            "title": "8 Best Free Form Builders in 2026 (Free Plans, Not Trials)",
            "domain": "tally.so",
            "snippet": null,
            "own_site": true
          },
          {
            "url": "https://fabric.so/comparison/best-free-form-builder",
            "title": "Best free form builder",
            "domain": "fabric.so",
            "snippet": null,
            "own_site": false
          }
        ],
        "mentioned": true,
        "sentiment": "positive",
        "web_search": true,
        "prompt_type": "pricing",
        "score_parts": {
          "depth": {
            "max": 15,
            "score": 15
          },
          "framing": {
            "max": 15,
            "score": 15
          },
          "accuracy": {
            "max": 5,
            "score": 5
          },
          "citation": {
            "max": 10,
            "score": 10
          },
          "visibility": {
            "max": 25,
            "score": 25
          },
          "competitive": {
            "max": 10,
            "score": 7
          },
          "recommendation": {
            "max": 20,
            "score": 20
          }
        },
        "brands_named": [
          "G2",
          "HubSpot Forms",
          "Wufoo",
          "Cognito Forms",
          "Stripe"
        ],
        "judge_reason": "Tally gets detailed, strongly positive coverage as the best overall option and the explicit final pick, alongside relevant form-builder alternatives.",
        "competitors_found": [],
        "competitors_named": [
          "HubSpot Forms",
          "Wufoo",
          "Cognito Forms",
          "Fillout",
          "forms.app"
        ]
      }
    ],
    "questions": [
      {
        "type": "pricing",
        "score": 85,
        "prompt": "Best free form builders for small businesses",
        "answers": 5,
        "branded": false,
        "cited_in": 5,
        "brands_named": [
          "Fillout",
          "Stripe",
          "HubSpot Forms",
          "Zoho Forms",
          "Google Workspace"
        ],
        "mentioned_in": 5,
        "best_position": 1,
        "searched_answers": 5,
        "competitors_named": [
          "Fillout",
          "HubSpot Forms",
          "Zoho Forms",
          "Cognito Forms",
          "Wufoo"
        ]
      }
    ],
    "competitors": [
      {
        "name": "Fillout",
        "mentions": 7,
        "answer_share": 47
      },
      {
        "name": "Microsoft Forms",
        "mentions": 3,
        "answer_share": 20
      },
      {
        "name": "Zoho Forms",
        "mentions": 3,
        "answer_share": 20
      }
    ],
    "citation_opportunities": [
      {
        "domain": "hubspot.com",
        "answers": 3,
        "examples": [
          {
            "url": "https://blog.hubspot.com/marketing/form-builder-tools?region=united-states",
            "title": "HubSpot's form builder guide"
          }
        ]
      }
    ]
  }
}

Keyword opportunities (answers at once)

bash
curl -X POST https://api.magistermarketing.com/v1/keywords/research \
  -H "Authorization: Bearer $MAGISTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"tally.so","seed":"online form builder","limit":15}'
json
{
  "data": {
    "domain": "tally.so",
    "seed": "online form builder",
    "broadened_seed": null,
    "partial": false,
    "failed_sections": [],
    "site": {
      "ranking_keywords": "100-1k",
      "paid_keywords": "under 10",
      "monthly_search_visits": "1k-10k"
    },
    "keywords": [
      {
        "keyword": "form online builder",
        "source": "suggestion",
        "opportunity": 78,
        "intent": "commercial",
        "demand": "10k-100k",
        "difficulty": "easy",
        "position": null,
        "cluster": "online form builder",
        "action": "Make a page that compares the options and makes your case."
      },
      {
        "keyword": "free online html form builder",
        "source": "suggestion",
        "opportunity": 58,
        "intent": "commercial",
        "demand": "1k-10k",
        "difficulty": "easy",
        "position": null,
        "cluster": "html",
        "action": "Make a page that compares the options and makes your case."
      }
    ],
    "clusters": [
      {
        "cluster": "online form builder",
        "keywords": 11
      },
      {
        "cluster": "website",
        "keywords": 5
      }
    ]
  },
  "credits_charged": 9.92,
  "request_id": "560c6fae-a58b-4a50-b9eb-059fd6531004"
}

Search competitors (answers at once)

bash
curl -X POST https://api.magistermarketing.com/v1/competitors/discover \
  -H "Authorization: Bearer $MAGISTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"tally.so","limit":6}'
json
{
  "data": {
    "domain": "tally.so",
    "competitors": [
      {
        "domain": "jotform.com",
        "overlap": 58,
        "standing": "ranks_higher",
        "search_reach": "100k+"
      },
      {
        "domain": "typeform.com",
        "overlap": 45,
        "standing": "about_even",
        "search_reach": "10k-100k"
      },
      {
        "domain": "forms.app",
        "overlap": 37,
        "standing": "ranks_lower",
        "search_reach": "10k-100k"
      }
    ],
    "site": {
      "search_reach": "1k-10k"
    },
    "note": null
  },
  "credits_charged": 3.2,
  "request_id": "1a18e09d-3822-41fd-9215-e7cf988cff42"
}

Page speed for real visitors (free, answers at once)

bash
curl -X POST https://api.magistermarketing.com/v1/web/page-speed \
  -H "Authorization: Bearer $MAGISTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tally.so"}'
json
{
  "data": {
    "origin": "https://tally.so",
    "score": 99,
    "rating": "needs_improvement",
    "devices": {
      "phone": {
        "score": 98,
        "rating": "needs_improvement",
        "metrics": {
          "largest_contentful_paint": {
            "p75": 2020,
            "rating": "good"
          },
          "interaction_to_next_paint": {
            "p75": 229,
            "rating": "needs_improvement"
          },
          "cumulative_layout_shift": {
            "p75": 0,
            "rating": "good"
          }
        }
      },
      "desktop": {
        "score": 100,
        "rating": "good",
        "metrics": {
          "largest_contentful_paint": {
            "p75": 1263,
            "rating": "good"
          },
          "interaction_to_next_paint": {
            "p75": 77,
            "rating": "good"
          },
          "cumulative_layout_shift": {
            "p75": 0.01,
            "rating": "good"
          }
        }
      }
    },
    "fixes": [
      {
        "metric": "interaction_to_next_paint",
        "rating": "needs_improvement",
        "fix": "The page is slow to respond to taps and clicks: break up long JavaScript tasks, defer third-party scripts and load chat or tracking widgets after the page is usable."
      }
    ],
    "field_data": true,
    "note": null,
    "source": "Chrome UX Report (CrUX), Google, CC BY 4.0"
  },
  "credits_charged": 0,
  "request_id": "673502b3-11ee-41a1-a4e3-4b6f9e4e18f8"
}

The rating is Google's pass mark: every metric must be good, so a score of 99 with one metric over its bar reads needs_improvement.

The full marketing audit (a job)

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://tally.so"}'

This one took 1 min 17 s:

json
{
  "job_id": "6a7defd2-d26b-4ab0-b0f6-a804e41a9856",
  "kind": "site_audit",
  "status": "succeeded",
  "created_at": "2026-11-11T04:08:51.896908+00:00",
  "finished_at": "2026-11-11T04:10:09.145871+00:00",
  "credits_charged": 103.74,
  "result": {
    "website_url": "https://tally.so",
    "status": "complete",
    "health": {
      "current": 64,
      "subscores": {
        "ai_search": {
          "current": 87
        },
        "google_search": {
          "current": 20
        },
        "website_and_content": {
          "current": 86
        }
      },
      "tabs": {
        "google_search": {
          "score_current": 20,
          "score_basis": "Keyword research: the site is on Google's first two pages for 4 of 10 keywords looked up.",
          "keywords": [
            {
              "demand": "1k-10k",
              "keyword": "free form builder",
              "position": null
            },
            {
              "demand": "1k-10k",
              "keyword": "free online form builder",
              "position": null
            },
            {
              "demand": "100-1k",
              "keyword": "no-code form builder",
              "position": null
            }
          ],
          "findings": [
            {
              "title": "No top-100 visibility for the listed searches",
              "detail": "Tally does not appear in the top 100 for any of the five listed searches, including “online form creator” and “online form maker,” each with 10k-100k monthly searches.",
              "severity": 5
            }
          ],
          "opportunities": [
            {
              "title": "Make a page for online form makers",
              "detail": "Create a page that directly answers searches like “online form creator” and “online form maker,” with examples of what people can build and a clear invitation to try Tally."
            }
          ]
        },
        "website_and_content": {
          "score_current": 86,
          "checklist": [
            {
              "note": "Found: Get started",
              "label": "Clear call to action",
              "status": "pass"
            },
            {
              "note": "Found: Organization, ContactPoint, WebSite, SoftwareApplication",
              "label": "Schema markup",
              "status": "pass"
            }
          ]
        }
      }
    }
  }
}