> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Heralded API

> Read your brands' AI visibility from a script, a spreadsheet or an AI assistant.

The Heralded API reads your brands' figures, prompts, answers, competitors, sources and actions. It is read-only, and it doesn't yet cover everything the app shows; the [API reference](/api-reference/v1/get-brands) lists what it serves. There are two ways in:

* **REST.** `GET` routes under `https://api.heralded.ai/v1`, described in the [API reference](/api-reference/v1/get-brands). Use them from scripts, notebooks and BI tools.
* **MCP.** The Model Context Protocol is how AI assistants connect to tools. Heralded runs an MCP server at `https://api.heralded.ai/v1/mcp` with one tool per route, for AI assistants and agents. An assistant can [sign in](/assistants) or [use a key](/connect-mcp).

Both read as the member who holds the credential, in one organization, which is what Core and Plus call a [workspace](/concepts/workspaces-and-brands#workspace). Neither can change anything.

## Quickstart

<Steps>
  <Step title="Create an API key">
    In Heralded, open **Settings**, choose **You**, then **API keys**, and create a key. Copy it now. It starts with `hrld_`, and Heralded never shows it again. See [API keys](/api-keys).
  </Step>

  <Step title="List your brands">
    ```bash theme={null}
    curl -H "Authorization: Bearer $HERALDED_API_KEY" https://api.heralded.ai/v1/brands
    ```

    ```json theme={null}
    { "brands": [{ "id": "8f2c1f4e-5a0b-4c7e-9d3a-2b6e1c0f9a11", "domain": "acme.com", "name": "Acme" }] }
    ```
  </Step>

  <Step title="Read a brand's overview">
    ```bash theme={null}
    curl -H "Authorization: Bearer $HERALDED_API_KEY" \
      https://api.heralded.ai/v1/brands/8f2c1f4e-5a0b-4c7e-9d3a-2b6e1c0f9a11/overview
    ```

    The overview holds all five figures over your selected `period`, defaulting to `1w`, with a descriptor of its report count, answer dates and excluded reports. Change compares the period with the preceding reports, as many as the period holds and at least four when available. It also holds the latest report's status line and citation metrics, top competitors, most cited sources, newest open actions, the next weekly and daily scan times, the daily scans since the last weekly report, the open action count and the readiness counts. [Figures in the API](/figures) describes the periods and fields.
  </Step>
</Steps>

## Every plan

The API and the MCP server are included on every plan, and no plan limits what they read. Each key has a [rate limit](/errors-and-limits#rate-limit).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.