# 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. Interviews are conducted by former investigative journalists with senior leaders, producing insights that reflect firsthand experience and context rarely captured in conventional research sources.

## Overview

* Call the [/companies](https://docs.auraresearch.ai/api-reference/api-reference/companies-search) endpoint to return the `company_id` which will be used as a query parameter when calling [/interviews](https://docs.auraresearch.ai/api-reference/api-reference/interviews).
* Call the [/interviews](https://docs.auraresearch.ai/api-reference/api-reference/interviews) endpoint to access full transcripts and metadata.
  * Use the query parameters to filter results by `company_id`, `company_ticker`, `company_name`, date, and many other options.
* Use the [/research-request](https://docs.auraresearch.ai/api-reference/api-reference/research-request) endpoint to create a new research request that will generate new interviews on the subject requested.
* Call the [/health](https://docs.auraresearch.ai/api-reference/api-reference/health) endpoint to verify your API key is valid and the service is operational.

## 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 | Base URL                                     |
| ----------- | -------------------------------------------- |
| Production  | `https://api.heron-intelligence.com`         |
| Sandbox     | `https://api-sandbox.heron-intelligence.com` |

## Make your first API call

With your API key, let's call the [/health](https://docs.auraresearch.ai/api-reference/api-reference/health) 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](https://docs.auraresearch.ai/overview/quickstart) to retrieve your first transcripts.
2. Explore the [API Reference](https://docs.auraresearch.ai/api-reference/api-reference) for detailed endpoint documentation.
3. Review [Data Models](https://docs.auraresearch.ai/documentation/data-models) to understand response structures.
4. Learn about [Error Handling](https://docs.auraresearch.ai/documentation/error-handling) for robust applications.