The Asheard API and MCP server

What you can connect

The Asheard API and the MCP server give your own scripts, dashboards and AI assistants read access to a workspace: projects, keyword rankings, AI visibility per engine, prompts, AI answers with the sources they cite and read, competitors, cited domains, page audits and the action plan. Reading never spends credits. The API and the MCP server are available on Pro and Agency plans; on Agency plans the action plan also includes each action's fix: the steps, the exact change and how to check it worked.

API keys

Workspace admins create keys under Workspace → API & MCP. Give each key a name (the app or the client it is for), copy it when it is shown, and keep it like a password: Asheard stores only a fingerprint of it and can't show it again. Revoke a key there and every app using it stops working at once. Each key can make 60 calls a minute.

Send the key in the Authorization header of every call, never in the address:

Authorization: Bearer ash_…

The REST API

All endpoints are GET and return JSON. A project is its id or its exact name. start and end are dates (YYYY-MM-DD); without them a call covers the last 30 days.

GET https://app.asheard.com/api/v1/me
GET https://app.asheard.com/api/v1/projects
GET https://app.asheard.com/api/v1/rankings?project=&keyword=&start=&end=&limit=&offset=
GET https://app.asheard.com/api/v1/projects/{project}/visibility
GET https://app.asheard.com/api/v1/projects/{project}/prompts
GET https://app.asheard.com/api/v1/projects/{project}/answers?prompt_id=&engine=&limit=&offset=
GET https://app.asheard.com/api/v1/projects/{project}/competitors
GET https://app.asheard.com/api/v1/projects/{project}/citations
GET https://app.asheard.com/api/v1/projects/{project}/plan
GET https://app.asheard.com/api/v1/projects/{project}/audits

curl -H "Authorization: Bearer ash_…" "https://app.asheard.com/api/v1/projects/Acme/plan"

Rankings return up to 500 rows per call and answers up to 100, newest first; use offset for the next page. The plan is as of today; the other AI endpoints count the answers checked between start and end. Errors come back as JSON with an error message: 401 for a missing or revoked key, 403 when the plan doesn't include the API, 404 for a project outside the workspace, 422 for a bad date, 429 when a key makes too many calls.

Fixes: apply, report, verified

On Agency plans the API lists every fix of a project: the open ones with the exact change to make, and the ones already applied with their check. Your agent (or you) makes the change on the site; Asheard never changes your site itself. Then report it, with a note on what changed, and Asheard checks it: a page fix (robots.txt, snippets, rendering, the opening, length, format, structured data) is audited again within a minute, free; any other fix is measured on its prompts over the next 14 days of scheduled checks against the 28 days before. The status says where it stands: open, checking, measuring, applied (nothing Asheard can check by itself), verified, not_fixed or unverified (no answers to compare). Mark done on Gaps and Fixes is the same step.

GET  https://app.asheard.com/api/v1/projects/{project}/fixes?status=open
GET  https://app.asheard.com/api/v1/projects/{project}/fixes/{key}
POST https://app.asheard.com/api/v1/projects/{project}/fixes/{key}/applied   {"note": "…"}
POST https://app.asheard.com/api/v1/projects/{project}/fixes/{key}/reopen

Write calls

With a key made to write (Agency plans), the API and the MCP server can also add prompts, pause or resume them, add competitors and keywords, and start runs. The plan's limits apply as in the app. Runs spend credits: send dry_run true first to get the checks, the credits and your balance; the MCP tool start_run only quotes unless it is told dry_run false.

POST  https://app.asheard.com/api/v1/projects/{project}/prompts       {"prompts": ["…"], "language": "de"}
PATCH https://app.asheard.com/api/v1/projects/{project}/prompts/{id}  {"is_active": false}
POST  https://app.asheard.com/api/v1/projects/{project}/competitors   {"name": "…", "website": "https://…"}
POST  https://app.asheard.com/api/v1/projects/{project}/keywords      {"keywords": ["…"], "country": "de", "language": "de"}
POST  https://app.asheard.com/api/v1/projects/{project}/runs          {"type": "ai_visibility", "dry_run": true}
GET   https://app.asheard.com/api/v1/runs/{type}/{id}

Webhooks

On Agency plans, add up to five https addresses under Workspace → API & MCP and pick the events: run.finished, alert, fix.new, fix.verified and fix.not_fixed. Each delivery is a JSON POST with the event in X-Asheard-Event and a signature in X-Asheard-Signature: t is the time, v1 the HMAC-SHA256 of the time, a dot and the body, with the webhook's secret. Compare it before you trust the message. A failed delivery is tried three times; after 20 failures in a row the webhook is switched off.

The MCP server

AI assistants that speak the Model Context Protocol (Claude, ChatGPT, Cursor, n8n and others) can use the same data as tools. Add a server with this address and your key as the Authorization header:

https://app.asheard.com/api/mcp

Claude, ChatGPT, Cursor and other apps that support sign-in can connect by the address alone: add it as a custom connector (MCP server), sign in to Asheard when the app asks, and approve it for your workspace. Workspace admins approve apps; the app reads the workspace, and on Agency plans you can also allow write calls. Disconnect it at any time under Workspace → API & MCP.

Apps that take a header instead use an API key:

claude mcp add --transport http asheard https://app.asheard.com/api/mcp --header "Authorization: Bearer ash_…"

Claude Desktop starts local servers only: use the small bridge from the Asheard MCP package (mcp/index.js, no dependencies, Node 18 or newer) and set ASHEARD_API_KEY to your key.

Tools: list_projects, get_rankings, get_ai_visibility, get_project_visibility, list_prompts, get_answers, get_competitors, get_citations, get_action_plan and get_page_audits. Try asking: which prompts lost visibility on Gemini this month, and what should I fix first? With get_action_plan on an Agency plan the assistant gets the exact change for each action and can apply it on your site with its own tools, then you check it in Asheard.

On Agency plans the assistant also gets list_fixes, and with a key made to write mark_fix_applied, reopen_fix, add_prompts, set_prompt_active, add_competitor, add_keywords, start_run and get_run: it can make a fix on your site with its own tools, report it, and come back for the verdict.

The connector token on the Reports page keeps working for Looker Studio, and on the MCP server for Agency plans as before. For anything new, use an API key.

A Claude skill for the WordPress fix loop

The skill teaches Claude the loop on a WordPress site: list the open fixes, ask you which to do, show each change before and after, apply it (in the page, the SEO plugin's robots.txt or schema settings, or WooCommerce's product fields), check it is live, report it to Asheard and come back for the verdict. Drafts such as correction e-mails and pitches stay drafts for you to send. It needs the Asheard connector with write calls allowed and access to the site, for example a WordPress application password.

Download the skill (.zip) · Upload the zip as a skill in Claude, then ask: work through the Asheard fixes for my site.