> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown is also available via `Accept: text/markdown`. Full corpus: [llms-full.txt](/llms-full.txt).

# The Signal API

Programmatic REST access to the cybersecurity market dataset behind [The Signal](https://signal.returnonsecurity.com) — funding rounds, M&A, companies, investors, and the analytics built on them. Build market maps, deal sourcing, and account enrichment on the same data that powers the dashboard.

- Get an API key: https://signal.returnonsecurity.com/account
- Interactive reference (Scalar): [/reference/](/reference/)
- Machine-readable contract: [/openapi.json](/openapi.json)
- Agent skill: [/skill.md](/skill.md)
- Product MCP (live): https://mcp.returnonsecurity.com/mcp

## Overview

The Signal API is a read-only REST API over Return on Security's curated cybersecurity market data — the same dataset behind The Signal dashboard and the weekly Return on Security newsletter. Every endpoint is a `GET` that returns JSON, authenticated with a Bearer key.

Base URL:

```
https://signal.returnonsecurity.com
```

The public surface spans domains across the curated endpoints (companies, investors, funding, M&A, rankings, distributions, plus entitlement/pricing helpers). See [reference.md](/reference.md) or [openapi.json](/openapi.json) for the full list.

**Access.** The API is part of **Enterprise**. The Pro add-on was retired on 2026-09-19; subscribers who already held it keep access. Manage your subscription and keys at [your account](https://signal.returnonsecurity.com/account).

## What you can build

### For investors & corporate development

- **Market mapping** — funded companies in a cybersecurity category, with round sizes, investors, and timing. `/companies` · `/category-data` · `/top-funding-rounds`
- **Deal sourcing & follow-on** — newly funded startups and stage velocity. `/funding/history` · `/stages/distribution`
- **Consolidation & acquirer tracking** — who's buying and which buyer types are active. `/top-acquisitions` · `/top-acquirers-by-volume` · `/buyer-type`
- **Investor benchmarking** — league tables and portfolio activity. `/top-investors` · `/investors/{name}`

### For go-to-market teams

- **Budget-signal targeting** — security companies by stage/category after a raise. `/companies` · `/category-data`
- **Account enrichment** — funding history, investors, valuation context for CRM. `/companies/{name}` · `/investors`

### For founders & operators

- **Benchmark your raise** — stage percentiles for your category. `/funding-stage-percentiles` · `/ranges/breakdown`
- **Category & competitive intel** — players and momentum. `/company-type` · `/category-data`

### For analysts, researchers & press

- **Sector trends & rankings** — funding totals, M&A activity, league tables. `/charts` · `/top-funding-rounds` · `/top-acquisitions`

## Why The Signal API

- **Security-specific, investment-grade** — curated cybersecurity dataset behind The Signal and the weekly Return on Security newsletter.
- **Built for agents, too** — same data over the Model Context Protocol at https://mcp.returnonsecurity.com/mcp (set up from your account).
- **One clean contract** — consistent JSON plus freshness and quota headers on every response.

## Quickstart

1. **Get a key.** Go to [Account → Developer → API](https://signal.returnonsecurity.com/account) and mint a key (`ros_live_…`). It is shown once — store it safely.
2. **Export it** so you never paste it inline:

```bash
export ROS_API_KEY="ros_live_…"
```

3. **Make your first call:**

```bash
curl -H "Authorization: Bearer $ROS_API_KEY" \
  "https://signal.returnonsecurity.com/api/v2/companies?limit=10"
```

A successful response is JSON plus headers for freshness (`X-Data-Freshness`), quota (`X-Quota-*`), and correlation (`X-Request-Id`). Browse every endpoint in the [API Reference](/reference.md).

## Authentication

Every request authenticates with an `Authorization: Bearer ros_live_…` header. Keys are minted, labelled, and revoked at [your account](https://signal.returnonsecurity.com/account). Access is checked on every request against your live entitlement (Enterprise, or a grandfathered add-on) — revoking a key takes effect immediately, and losing entitlement revokes your keys.

**Treat a key like a password.** Never commit it to source control, never put it in a URL or client-side code, and always call over HTTPS. Read it from `$ROS_API_KEY`. A leaked key can be revoked and re-minted from your account at any time.

## Plans & access

The API is a paid product, included with **Enterprise**. Every API caller gets the **full** curated dataset and all public endpoints; there is no cut-down data tier.

| Plan       | API access               | Quota     |
| ---------- | ------------------------ | --------- |
| Free       | Dashboard only — no API  | —         |
| Pro        | Dashboard + MCP — no API | —         |
| Enterprise | Full API, all endpoints  | Unlimited |

REST API access is **Enterprise-only** as of 2026-09-19. The Pro API add-on was retired on that date; subscribers who already held it keep access as a closed, grandfathered cohort. To get an API key, see [Enterprise](https://signal.returnonsecurity.com/pricing#enterprise).

Pro is priced per seat; each subscription covers one user. Enterprise is for organisations and teams, with tailored team seats, integrations, and support. Pricing is custom — [contact us about your requirements](https://signal.returnonsecurity.com/enterprise?type=integration&source=docs).

Embedding, OEM, redistribution and AI training, fine-tuning, evaluation or downstream model use require explicit licensing terms. A Pro subscription or an enquiry does not grant those rights.

### Premium fields

A few response fields are **premium intelligence** — keys are always present; values may be `null` on the free dashboard. Today that includes the investor government-linkage set on `/investors`: `government_linked_tier` (`govt_chartered` / `defence_cvc` / `sovereign_wealth`), `government_linked_country`, and `government_linked_since`. Each premium field is marked in the [API Reference](/reference.md).

## Rate limits & quotas

Enterprise keys are **uncapped**. The two windows below are the caps that
apply to the closed, grandfathered add-on cohort; every key still returns the
`X-Quota-*` headers, which are the authoritative figures for your key:

| Window  | Limit           | Resets            |
| ------- | --------------- | ----------------- |
| Daily   | 1,000 requests  | 00:00 UTC         |
| Monthly | 30,000 requests | 1st of month, UTC |

Response headers:

| Header                                 | Meaning                                                |
| -------------------------------------- | ------------------------------------------------------ |
| `X-Quota-Daily-Limit` / `-Remaining`   | Daily allowance and what's left                        |
| `X-Quota-Monthly-Limit` / `-Remaining` | Monthly allowance and what's left                      |
| `Retry-After`                          | Seconds until the exhausted window resets (on a `429`) |
| `X-Data-Freshness`                     | Day the dataset last changed (`YYYY-MM-DD`)            |
| `X-Request-Id`                         | Correlation id for support                             |

When a window is exhausted the API returns `429` with `{ "error": …, "code": "quota_exceeded", "window": "daily" }` and a `Retry-After` header. Honor it and retry after the reset.

## Errors

Errors use a consistent JSON envelope — an `error` message and a stable machine-readable `code`:

```json
{ "error": "API quota exceeded", "code": "quota_exceeded" }
```

| Status | Code                  | Meaning                                               |
| ------ | --------------------- | ----------------------------------------------------- |
| 401    | `auth_required`       | Missing or invalid key                                |
| 403    | `api_access_required` | Key valid, but no active API entitlement              |
| 404    | `not_found`           | No entity matches the path parameter                  |
| 429    | `quota_exceeded`      | Daily or monthly window exhausted — see `Retry-After` |
| 503    | `quota_unavailable`   | Metering temporarily unavailable — retry shortly      |
| 500    | —                     | Unexpected server error — quote `X-Request-Id`        |

Every error response includes an `X-Request-Id`. Including it when you contact support lets us pull the exact request from our logs.