> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fanhaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Authenticate with an API key to read fans, sales, events, and merch.

The Fanhaven API is a REST interface for server-to-server integrations. Create a key in the dashboard, then call the endpoints documented here.

## Get started

<Steps>
  ### Create a key

  In the dashboard, go to **Settings → API → API Keys** and click **Create key**. Copy the secret immediately — it is shown once.

  ### Authenticate

  Send the key as a Bearer token:

  ```bash theme={null}
  curl "https://api.fanhaven.com/v1/fans" \
    -H "Authorization: Bearer fh_live_..."
  ```

  ### Read data

  List endpoints return paginated `items`. Amounts are integers in the smallest currency unit (cents).
</Steps>

## Base URL

```
https://api.fanhaven.com/v1
```

Keys are bound to the tour they were created on. Fan endpoints are artist-wide. Transactions, events, and merch stay on that tour.

## Response shape

Successful responses:

```json theme={null}
{
  "success": true,
  "data": {}
}
```

List responses nest pagination inside `data`:

```json theme={null}
{
  "success": true,
  "data": {
    "items": [],
    "page": 1,
    "per_page": 25,
    "total": 0,
    "has_more": false
  }
}
```

Errors:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is required to access this route"
  }
}
```

## Rate limits

**120 requests per minute** per key.

Exceeding the limit returns `429` with code `too_many_requests`.

## What to call

| Resource                                    | Use it for                                 |
| ------------------------------------------- | ------------------------------------------ |
| [Fans](/api-reference/fans)                 | Pull fan records into a CRM or warehouse   |
| [Transactions](/api-reference/transactions) | Sales into your warehouse or finance tools |
| [Events](/api-reference/events)             | Tour dates and venues                      |
| [Merch](/api-reference/merch)               | Catalog, prices, and variants              |
| [Webhooks](/api-reference/webhooks)         | Push events instead of polling             |