API and MCP

Settings, API and MCP, create a key. It is shown once and only its hash is stored, so if you lose it, revoke it and make another. Keys expire after a year and can be revoked at any time, which takes effect on the next request.

curl https://www.aureoapp.ai/api/v1/me \
  -H "Authorization: Bearer aureo_your_key"

Every success is { "data": ... } and every failure is { "error": { "code", "message" } }, so one unwrapping function covers the whole API.

• GET/api/v1/me
  The key, its scopes, and the brands it can read.
• GET/api/v1/brands
  Those brands on their own.
• GET/api/v1/brands/{id}
  Everything about one brand in one call: metrics, gaps, legibility, traffic and cited pages.

Add it as an HTTP MCP server with your key as a bearer token. It works with Claude, Cursor and anything else that speaks the protocol.

https://www.aureoapp.ai/api/mcp

• list_brands
  The brands in this workspace. Call it first: every other tool needs an id.
• get_visibility
  Score with its weights, mention rate, share of voice, position, citations, and the weekly history.
• get_gaps
  The queries where a competitor gets through and you do not, per engine.
• get_legibility
  Whether an assistant can read the site, and every failing check with its fix.
• get_traffic
  Humans, visits credited to the assistant that sent them, and crawler requests.
• get_cited_pages
  The pages assistants cite, how often, whether they still answer, and what kind they are.

A brand id is always checked against the workspace your key belongs to, so an id from somewhere else returns nothing rather than somebody else's week.

• 401 unauthorized
  No key, or a key that is not valid. Revoked, expired and unknown all answer the same way.
• 403 plan_required
  The key is fine and the plan does not include the API.
• 404 not_found
  No brand by that id in this workspace. A key never carries a brand.

Add an https endpoint in Settings and we post to it when a scan finishes. Three attempts, one second apart, and every attempt is recorded whether it succeeded or not. A 4xx is taken as your answer and not retried; a 5xx or a timeout is.

Each delivery carries three headers: x-aureo-delivery, x-aureo-timestamp and x-aureo-signature. Sign deliveryId.timestamp.rawBody with HMAC SHA-256 and your signing secret, compare it to the value after v1=, reject anything older than a few minutes, and deduplicate on the delivery id.

const expected =
  'v1=' + createHmac('sha256', secret)
    .update(`${deliveryId}.${timestamp}.${rawBody}`)
    .digest('hex');

The delivery id and the timestamp are inside the signature on purpose. Signing the body alone would let anybody who captures one delivery replay it for ever, and you would have no way to tell.