# Overview (/docs/api)

Signal's REST API gives your code the same data as the dashboard: brands, prompts, competitors, runs, and the visibility, citation, and query fan-out analytics behind them. API access is included on every plan.

**Base URL:** `https://app.signal.metricshive.com/api/v1`

The OpenAPI spec is at [`https://app.signal.metricshive.com/api/v1/openapi.json`](https://app.signal.metricshive.com/api/v1/openapi.json), and the same reference is browsable inside the app at **Organization Settings → API**.

## Authentication [#authentication]

Every request carries an API key as a Bearer token in the `Authorization` header:

```http
Authorization: Bearer signal_...
```

Organization admins issue keys from **Organization Settings → API Keys**. Keys belong to the organization, not to a brand. When you create a key you choose:

- **Access** — Read-only, or read and write
- **Brands** — All brands, or only specific ones
- **Expires** — An expiry date, or never

The key is shown once, when you create it, so store it somewhere safe. Revoke a key from the same page and it stops working immediately. The examples below read the key from a `SIGNAL_API_KEY` environment variable.

## Scopes [#scopes]

Each operation lists the scope it requires in `x-signal-scopes`:

| Scope | Grants |
|-------|--------|
| `read` | Read brands, prompts, competitors, runs, citations, analytics, and the organization's plan and usage |
| `write` | Everything `read` grants, plus creating, updating, and deleting brands, prompts, and competitors |

Operations marked `x-signal-admin-only`, such as report generation, brand analysis, and deleting a prompt, aren't available to organization keys. To stop tracking a prompt without losing its history, update it with `enabled: false`. No key can change your subscription or payment details through the API.

## Examples [#examples]

### List Your Brands [#list-your-brands]

```bash
curl https://app.signal.metricshive.com/api/v1/brands \
  -H "Authorization: Bearer $SIGNAL_API_KEY"
```

### Get a Brand's Analytics [#get-a-brands-analytics]

```js
const params = new URLSearchParams({
	start: "2026-10-01T00:00:00Z",
	end: "2026-11-01T00:00:00Z",
	model: "chatgpt",
});

const response = await fetch(
	`https://app.signal.metricshive.com/api/v1/brands/${brandId}/analytics?${params}`,
	{ headers: { Authorization: `Bearer ${process.env.SIGNAL_API_KEY}` } },
);
const analytics = await response.json();
```

### Create a Prompt [#create-a-prompt]

```python
import os
import requests

response = requests.post(
    "https://app.signal.metricshive.com/api/v1/prompts",
    headers={"Authorization": f"Bearer {os.environ['SIGNAL_API_KEY']}"},
    json={
        "brandId": "YOUR_BRAND_ID",
        "value": "What's the best project management tool for small agencies?",
        "tags": ["project management"],
    },
)
response.raise_for_status()
print(response.json())
```

## Conventions [#conventions]

- Timestamps are ISO 8601 in UTC; dates are `YYYY-MM-DD`.
- Analytics endpoints take a `start` and `end` timestamp and return the whole window in one response.
- Lists take `page` (starting at 1) and `limit` (up to 100) and return a `pagination` object.
- Errors share one shape, `{ error, message, code }`, where `code` is a stable machine-readable string.
- A brand your key can't reach returns `404`, the same as one that doesn't exist. A key without the required scope gets `403`.
- Plan limits and per-key rate limits apply to every key.

Prefer to work with your data from an AI assistant? The [MCP server](/docs/api/mcp) offers the same data with the same permissions.

## Endpoints [#endpoints]

Browse the endpoints in the sidebar, grouped by resource:

- **Brands** — Manage brand records
- **Prompts** — Manage a brand's prompts
- **Competitors** — Manage a brand's competitors
- **Snapshots** — Aggregated analytics for a single prompt
- **Analytics** — Visibility, share of voice, citations, per-model, per-prompt, and query fan-out metrics
- **Runs** — Individual prompt evaluations with the full response
- **Tags** — The prompt tags in use on a brand
- **Opportunities** — The latest generated opportunities for a brand
- **Organizations and Billing** — Your organization and its plan and usage
- **Models** — The AI platforms Signal can track