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

# API reference

> Base URL, authentication, ids, units and endpoints of the Hoppier REST API (closed beta).

> [!NOTE]
>
> The Hoppier API is in **closed beta**. Everything on this site runs in production today. Anything that doesn't run yet is on the [Coming soon](/guides/coming-soon.md) page, not here.

## Base URL

```text theme={null}
https://app.hoppier.com/api/v1
```

Requests and responses are JSON over HTTPS. Send `Content-Type: application/json` with every request that has a body.

## Authentication

Send your API key as a bearer token:

```text theme={null}
Authorization: Bearer hk_live.…
```

Keys are issued by Hoppier during the beta. See [Authentication](/guides/authentication.md).

## Endpoints

| Endpoint | What it does |
| - | - |
| [`GET /validate`](/api-reference/validate) | Check a key and see which admin and company it belongs to. |
| [`GET /programs`](/api-reference/programs/list) | List the programs in your company. |
| [`GET /programs/{program}`](/api-reference/programs/get) | Get one program. |
| [`POST /participants`](/api-reference/participants/add) | Add a person to a program and get their invite link. |

Webhook: [`card.claimed`](/api-reference/webhooks/card-claimed).

## Ids and units

Ids are strings with a prefix: `prg_` for programs, `pcpt_` for participants, `ad_` for addresses. Pass them back unchanged.

Amounts don't all use the same unit. Each one is marked on its page:

| Where | Unit | \$25.00 is |
| - | - | - |
| A program's `amount`, in every response | cents | `2500` |
| `amount` when you [add a participant](/api-reference/participants/add.md) | dollars | `25` |
| `data.amount` in the [`card.claimed` webhook](/api-reference/webhooks/card-claimed) | dollars | `25` |

Program dates are Unix timestamps in milliseconds, sent as strings. More in [Concepts](/guides/concepts.md).

## Safe retries

`POST /participants` accepts an `Idempotency-Key` header: a UUID you generate per add and reuse on retries, so a retried request never adds anyone twice. See [Errors and rate limits](/guides/errors-and-rate-limits.md#retrying-safely).

## Versioning

The API has no version header. We add fields and error codes without notice, so ignore anything you don't recognise. We don't rename or remove a documented field, or change its meaning, without announcing it on the [changelog](/changelog.md) first.

## OpenAPI

This reference is generated from an OpenAPI 3.1 file. To generate a client or import the API into Postman, download the file from the page menu at the top of any page (**Download API spec**).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.