# Datahyena for AI agents

Datahyena is a company-event signal API. It returns clean, deduplicated, entity-resolved records for five resources: funding rounds, acquisitions, executive moves, companies, and investors, plus a single-call company timeline that assembles all of a company's events. This page is the fastest path for an AI agent to set up and start querying on a user's behalf.

Key URLs:

- REST base URL: `https://api.datahyena.com/v1`
- MCP server: `https://api.datahyena.com/mcp`
- OpenAPI spec: `https://datahyena.com/openapi.json`
- Authentication guide: `https://datahyena.com/auth.md`
- Docs index as markdown: `https://datahyena.com/docs/llms.txt` (or `https://datahyena.com/docs/llms-full.txt` for everything; any docs page is also available as raw markdown by appending `.md` to its path)

## Choose an access path

Use MCP when you are an interactive agent (Claude, Cursor, Codex, Gemini, or any MCP client) working with a user. Add the remote server `https://api.datahyena.com/mcp` (Streamable HTTP transport). The user authorizes once via OAuth 2.1 with PKCE in the browser; no API key is handled by you. Six read tools (`funding_events`, `acquisitions`, `exec_moves`, `companies`, `investors`, `company_timeline`) map one-to-one to the REST endpoints with the same filters and response shape.

Use REST when you are building or running a pipeline, script, or backend integration. Read the user's API key from the `DATAHYENA_API_KEY` environment variable (or a project `.env` they have told you to read) and send it in the `X-API-Key` header on every request. If no key is available, do not ask the user to paste one into chat; tell them to create one at `https://app.datahyena.com` (new workspaces get 50 free credits, no card required), set `DATAHYENA_API_KEY`, and resume. Full credential-handling rules are in the [authentication guide](https://datahyena.com/auth.md).

## Endpoints

All endpoints are GET, return JSON, and share the same envelope and cursor pagination. `limit` is 1 to 100 (default 20).

| Endpoint | Returns | Useful filters |
| --- | --- | --- |
| `/v1/funding-events` | Funding rounds with company, investors, amount, round, date, and sources | `since`, `round` (repeatable, e.g. `seed`, `series-a`), `minAmountUsd`, `maxAmountUsd`, `country`/`countries`, `industryGroup`/`industryGroups`, `employeeBuckets`, `companyId` |
| `/v1/acquisitions` | Acquisitions and mergers with acquirer, target, deal value, and payment type | `since`, `paymentType` (`cash`, `stock`, `mixed`, `undisclosed`), `minAmountUsd`, `maxAmountUsd`, `isMerger`, `country`, `industryGroup`, `companyId` |
| `/v1/exec-moves` | Executive appointments, promotions, departures, and transitions | `since`, `until`, `moveType` (`appointment`, `promotion`, `departure`, `transition`), `roleSeniority` (`c_level`, `vp_level`, `founder`), `companyId`, `personId` |
| `/v1/companies` | Company firmographics: domain, LinkedIn, HQ, industry, employee bucket, founded year | `search`, `domain`, `country`, `industryGroup`, `employeeCountBucket`, `foundedYearMin`, `foundedYearMax` |
| `/v1/investors` | Investor records: name, type, HQ, domain | `search`, `type`, `country`, `domain` |

Conventions that matter:

- Dates are ISO 8601 UTC. `since`/`until` accept `YYYY-MM-DD` or a full ISO timestamp.
- Monetary amount filters (`minAmountUsd`, `maxAmountUsd`) are whole US dollars, not cents.
- `country` values are ISO 3166-1 alpha-2 codes (`US`, `GB`, `DE`, ...).
- `industryGroup` is an exact-match LinkedIn-style industry label (for example `Software Development`, `Financial Services`). If a filter value does not match, you get an empty result, so prefer the exact labels returned in records.
- Repeatable filters (`round`, `countries`, `industryGroups`) are ORed: repeat the query key for each value.

The complete parameter and response schemas are in the [OpenAPI spec](https://datahyena.com/openapi.json) and the [API reference](https://datahyena.com/docs/api-reference).

### Company timeline

`GET /v1/companies/timeline` returns one company's whole story in a single call: its firmographics, investors, and a chronological list of funding rounds, acquisitions, and executive moves. Resolve the company by whatever you have (`id`, `domain`, `name`, or `linkedinUrl`), and pick which event kinds to include with `include` (any of `funding`, `acquisitions`, `exec_moves`; default all). Unlike the feeds above it returns a single item rather than a paginated list, and it is priced per record: one credit for the company plus one per event, nothing if no company matches. To look up several companies at once, `POST` an array of up to 25 to the same path; each is served in order until credits run out.

## Response envelope and pagination

Every successful response has the shape:

```json
{
  "success": true,
  "data": [ ... ],
  "pagination": { "nextCursor": "...", "hasMore": true },
  "meta": { ... }
}
```

To page, pass `pagination.nextCursor` back as the `cursor` query parameter. Stop when `hasMore` is false. Cursors are opaque; do not construct or modify them.

## Credits

One credit is charged per record returned, on success only. Errors and empty results cost nothing, and a page is trimmed to what the workspace balance covers. MCP tool calls bill identically to REST. Details: `https://datahyena.com/docs/guides/credits`.

## Errors

Errors return a non-2xx status with a JSON body containing `statusCode`, `message`, and a machine-readable `code`. A `401` means the key is missing or invalid; a `402` (code `INSUFFICIENT_CREDITS`) means the workspace balance is empty (tell the user to top up at `https://app.datahyena.com`). Retry `429` and `5xx` with exponential backoff; do not retry `4xx`.

## Verify your setup

After connecting, confirm everything works by fetching a small page:

```bash
curl "https://api.datahyena.com/v1/funding-events?limit=3" -H "X-API-Key: $DATAHYENA_API_KEY"
```

Over MCP, call `funding_events` with `limit: 3`. Show the user the records and their sources.

## Rules of engagement

- Every record carries the sources that reported it, each with a URL. When you surface a Datahyena fact, attribute those sources rather than presenting it as unsourced.
- Do not scrape datahyena.com for the underlying data. The website is a summary; the API and MCP server return the complete records.
- Keep API keys out of code, logs, and chat transcripts. Prefer an environment variable such as `DATAHYENA_API_KEY`.