# The Signal API — full documentation corpus

> Generated from index.md + reference.md. Prefer individual .md pages when you only need one section.

---

## Page: Overview & guides
Source: https://docs.returnonsecurity.com/index.md

> 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 or a lapsed add-on takes effect immediately.

**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.

---

## Page: API Reference
Source: https://docs.returnonsecurity.com/reference.md

> 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).

# API Reference — The Signal API

Programmatic access to Return on Security's cybersecurity market dataset — funding rounds, acquisitions, companies, investors, and analytics.

Interactive HTML reference (Scalar): [/reference/](/reference/).
Machine-readable OpenAPI 3.1 contract: [/openapi.json](/openapi.json).

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

Authenticate every request with `Authorization: Bearer ros_live_…`.
See [index.md](/index.md) for quickstart, plans, quotas, and errors.

## Endpoints

Generated from the public OpenAPI spec (same file served at `/openapi.json`).

- `GET /api/v2/acquisition-category-data` — Acquisition data broken down by category
- `GET /api/v2/acquisition-geo-data` — Acquisition data broken down by target-company country
- `GET /api/v2/buyer-type` — Acquisitions grouped by buyer type (PE, Strategic, etc.)
- `GET /api/v2/category-data` — Funding data broken down by category
- `GET /api/v2/charts` — Main charts data with funding and acquisition aggregations
- `GET /api/v2/companies` — List all tracked companies
- `GET /api/v2/companies/{name}` — Get detailed data for a specific company
- `GET /api/v2/company-type` — Acquisitions grouped by company type
- `GET /api/v2/entitlement` — The caller's current plan, API entitlement, and remaining quota. Poll this (at most once a minute) to detect an upgrade landing instead of retrying a data endpoint; it answers while entitlement is lapsed, which is exactly when it matters.
- `GET /api/v2/filter-options` — Available filter options for the UI
- `GET /api/v2/funding-stage-percentiles` — Funding amount percentile heatmap by stage
- `GET /api/v2/funding/history` — Historical funding data over time
- `GET /api/v2/funding/instrument-breakdown` — Public-market capital by instrument type (senior notes, convertible notes, ATM equity, warrant activity) over time
- `GET /api/v2/investors` — List all tracked investors
- `GET /api/v2/investors/{name}` — Get detailed data for a specific investor
- `GET /api/v2/ma/history` — Annual M&A history — deal counts and disclosed values per year (exit-type breakdown for Pro callers)
- `GET /api/v2/pricing` — Machine-readable pricing catalog — plans, prices, and call allowances. Public and never quota-gated; the `upgrade.pricing_url` every paywall/quota refusal points at.
- `GET /api/v2/ranges/breakdown` — Transaction range breakdown analysis
- `GET /api/v2/stages/distribution` — Funding stage distribution analysis
- `GET /api/v2/top-acquirers-by-volume` — Most active acquirers by deal count
- `GET /api/v2/top-acquisitions` — Largest acquisitions ranked by amount
- `GET /api/v2/top-funding-rounds` — Largest funding rounds ranked by amount
- `GET /api/v2/top-investors` — Most active investors by deal count

## Related

- Guides: [index.md](/index.md)
- OpenAPI: [openapi.json](/openapi.json)
- Product MCP (live): https://mcp.returnonsecurity.com/mcp
- MCP server card: https://signal.returnonsecurity.com/.well-known/mcp.json

---

## OpenAPI
Source: https://docs.returnonsecurity.com/openapi.json

The machine-readable OpenAPI 3.1 contract is served at `/openapi.json` (not inlined here).