> For the complete documentation index, see [llms.txt](https://docs.heron-intelligence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heron-intelligence.com/overview/readme.md).

# Getting Started with Heron Intelligence

Heron Intelligence's API gives programmatic access to its interview transcript library so teams can quantify management quality, analyze executive behavior, and extract business intelligence at scale. The library draws on four research datasets — human, researcher-led diligence conducted by former investigative journalists with senior operators, former employees, customers and competitors, alongside AI-conducted diligence with broader and faster coverage. Every interview reports which dataset produced it; see [Data Providers](/documentation/data-providers.md).

## Overview

* Call the [/companies](/api-reference/api-reference/companies-search.md) endpoint to return the `company_id` which will be used as a query parameter when calling [/interviews](/api-reference/api-reference/interviews.md).
* Call the [/interviews](/api-reference/api-reference/interviews.md) endpoint to access full transcripts and metadata.
  * Use the query parameters to filter results by `company_id`, `company_ticker`, `company_name`, date, due-diligence type, data source provider, and many other options.
* Call the [/people](/api-reference/api-reference/people.md) endpoint to find an executive or expert by name or title and list every interview they appear in.
* Use the [/research-request](/api-reference/api-reference/research-request.md) endpoint to create a new research request that will generate new interviews on the subject requested — free-form, or from a standard template.
* Call the [/data-sources](/api-reference/api-reference/data-sources.md) endpoint to see which of the four [data providers](/documentation/data-providers.md) your API key can read.
* Register a [/webhooks](/api-reference/api-reference/webhooks.md) subscription to be notified as transcripts are delivered against your projects, instead of polling.
* Use the [/watchlist](/api-reference/api-reference/watchlist.md) endpoints to create and manage watchlist records.
* Call the [/health](/api-reference/api-reference/health.md) endpoint to verify your API key is valid and the service is operational.

Prefer to work through an LLM? The same catalog is exposed over the [Heron Intelligence MCP server](/overview/mcp.md).

## Before you begin

All endpoints require an API key passed via the `x-api-key` header. This provides secure, simple authentication for accessing the Heron Intelligence API. Contact your Heron Intelligence administrator or check your account dashboard to obtain your API key.

## Servers

| Environment   | URL                                          |
| ------------- | -------------------------------------------- |
| API           | `https://api.heron-intelligence.com`         |
| Sandbox       | `https://api-sandbox.heron-intelligence.com` |
| Documentation | `https://docs.heron-intelligence.com`        |

The [sandbox](/api-reference/api-reference/sandbox.md) is a non-production environment with the same API and authentication, for safely building and testing your integration.

## Make your first API call

With your API key, let's call the [/health](/api-reference/api-reference/health.md) endpoint to check that the API key is working and the Heron Intelligence API is operational:

```bash
curl --request GET \
  --url "https://api.heron-intelligence.com/api/v1/health" \
  --header 'x-api-key: <YOUR_API_KEY>'
```

Expected response:

```json
{
    "status": "ok",
    "service": "api",
    "timestamp": "2025-11-21T15:11:16.478000+00:00"
}
```

## Next Steps

1. Follow the [Quickstart Guide](/overview/quickstart.md) to retrieve your first transcripts.
2. Explore the [API Reference](/api-reference/api-reference.md) for detailed endpoint documentation.
3. Review [Data Models](/documentation/data-models.md) to understand response structures.
4. Read [Data Providers](/documentation/data-providers.md) to understand where each interview comes from and how to report it.
5. Learn about [Error Handling](/documentation/error-handling.md) for robust applications.