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

# Build with the API

> Run a sample feed app, connect it to live data, then call the REST API directly.

Run a small Next.js app that shows a Centaur feed, first with sample data and then with live data. Its request code is plain TypeScript, so you can move it into any backend later.

## 1. Run the starter app with sample data

You need Node.js 24 and npm. You do not need an account.

```sh theme={null}
git clone https://github.com/centaur-io/centaur-api-examples
cd centaur-api-examples
npm ci
npm run dev
```

Open [http://localhost:3000](http://localhost:3000). You see three fictional posts under a **Sample data** label. Choose an asset or select **Refresh** to read the feed again.

## 2. Switch to live data

1. Create an API key in [API key settings](https://app.centaur.io/settings/api-keys). You need an active Centaur account with a verified email; see [Get access](/guides/overview/authentication.md#create-an-account). New keys include the `feed.read` scope this app needs.
2. Copy `.env.example` to `.env.local`.
3. In `.env.local`, set `CENTAUR_DATA_MODE=live` and set `CENTAUR_API_KEY` to your key.
4. Restart `npm run dev`.

The label changes to **Live API mode** and recent activity loads. If the key is missing or lacks `feed.read`, the page shows an error. It never falls back to sample data.

> [!WARNING]
>
> Keep the API key on your server. Never put it in a `NEXT_PUBLIC_` variable or browser code. Anyone who can reach a public deployment of this app spends the key's quota.

## 3. Make it yours

| To change | Edit |
| - | - |
| The layout and states | `app/feed.tsx` |
| The assets in the picker | `lib/selections.ts`, with IDs from [Find IDs](/integrations/find-ids.md) |
| How requests are made | `lib/centaur.ts`. It has no Next.js or React imports, so you can copy it into another TypeScript backend. |

## Call the API directly

Every request goes to `https://api.centaur.io/v2` with your key in the `x-api-key` header. Set the key in your terminal first:

```sh theme={null}
export CENTAUR_API_KEY=your-key
```

The examples repository also has [TypeScript recipes](https://github.com/centaur-io/centaur-api-examples/tree/e56d8e26fb58892cf6b2762503c316fd2a94c7bf/recipes) that run on Node.js 24 with no installation. They use the same parameter names as REST.

### Read and filter the feed

```sh theme={null}
curl --fail-with-body --get 'https://api.centaur.io/v2/feed' \
  -H "x-api-key: $CENTAUR_API_KEY" \
  --data-urlencode 'assetIds=1,10' \
  --data-urlencode 'limit=20'
```

Omit `assetIds` for the general feed. Add `traderIds=42` to narrow to a trader. Different filters intersect. An empty `results` array means no matching activity. Look up IDs once during setup with [Find IDs](/integrations/find-ids.md), not before every read.

> [!NOTE]
>
> The `assetClass` filter is not available in production yet. Do not rely on it until this note is removed.

Once it is available, add `assetClass=crypto` or a comma-separated list of supported classes. It works alongside asset and trader filters.

### Read the next page

Copy `meta.nextCursor` from the previous response and keep the same filters:

```sh theme={null}
curl --fail-with-body --get 'https://api.centaur.io/v2/feed' \
  -H "x-api-key: $CENTAUR_API_KEY" \
  --data-urlencode 'assetIds=1,10' \
  --data-urlencode 'limit=20' \
  --data-urlencode "cursor=$NEXT_CURSOR"
```

Stop when `meta.hasMore` is `false`. Do not read or change the cursor. To poll for new activity instead, see [Partner feed](/guides/rest/feed.md#poll-for-changes).

### Read asset positioning

> [!NOTE]
>
> `GET /v2/assets/positioning` is pending release. Use it only after it is available in your environment.

This read needs the `stats.read` scope.

```sh theme={null}
curl --fail-with-body --get 'https://api.centaur.io/v2/assets/positioning' \
  -H "x-api-key: $CENTAUR_API_KEY" \
  --data-urlencode 'assetIds=1'
```

A snapshot with zero positions is valid data. An asset listed in `meta.missingAssetIds` is unavailable.

### Handle errors

Run curl with `--include --fail-with-body` to see the HTTP status, headers, and error body. In the TypeScript recipes, catch `CentaurApiError` to read `status`, `code`, `requestId`, and `retryAfter`. Network failures and timeouts keep their native errors. The client does not retry on its own.

* `401` or `403`: check the key and its scopes.
* `422`: check your parameters.
* `429` or a temporary failure: wait for `Retry-After`, then retry.

Keep upstream error details on your server and show visitors a safe message. [Errors and limits](/api-reference/conventions/errors.md) lists every status.

## Next steps

* [Data reads](/guides/rest/data-reads.md): every read, its scope, and which one answers which question.
* [Partner feed](/guides/rest/feed.md): pagination, polling for changes, and freshness.
* [Webhooks](/guides/rest/webhooks.md): receive new activity instead of polling.
* [API reference](/api-reference/overview.md): every endpoint, parameter, and field.


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