> ## 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.

# REST Overview

> Make your first call against the Centaur REST API.

Use REST when you want a direct integration with predictable request and response behavior.

## Base URL

```text theme={null}
https://api.centaur.io/v2
```

v1 is served at `https://api.centaur.io/v1`. Moving from `partners.centaur.io`? See [Migrating from partners.centaur.io](/guides/migrating-from-partners).

## Versions

Use `/v2/*` for new integrations. It provides every data read, including the pure trader directory and separate activity collection. Existing v1 clients can migrate incrementally. The [migration guide](/guides/rest/trader-directory-migration) explains trader contract changes and pagination.

Each version has its own OpenAPI document. Use `/v2/openapi.json` for v2 or `/v1/openapi.json` for v1. The existing `/openapi.json` URL continues to serve v1. Select a version in the API reference or Swagger UI.

## Auth

Send your Centaur API key in the `x-api-key` header.

## First request

```bash theme={null}
curl -s 'https://api.centaur.io/v2/events?limit=10' \
  -H 'x-api-key: <api-key>'
```

## What REST gives you

* Scope-gated reads across the partner feed, discovery, events, messages, generated summaries, positions, and stats
* Forward-only cursor pagination on list endpoints
* Response envelopes with stable request IDs and echoed applied bounds where relevant
* A generated OpenAPI reference with endpoint, parameter, and schema details
* A secondary Swagger UI if you want a quick interactive view

## Current endpoint families

* `GET /v2/traders`
* `GET /v2/traders/activity`
* `GET /v1/traders` (legacy)
* `GET /v2/assets`
* `GET /v2/events`
* `GET /v2/messages`
* `GET /v2/feed`
* `GET /v2/channel-summaries`
* `GET /v2/aggregate-summaries`
* `GET /v2/positions`
* `GET /v2/positions/open`
* `GET /v2/traders/stats`
* `GET /v2/assets/stats`
* `GET /v2/traders/rankings`
* `GET /v2/activity-summaries`
* `GET /v2/openapi.json`

## Operational endpoint

* `GET /healthz`

## Pagination essentials

* `limit` accepts up to `200` on general list reads and up to `100` source-message groups on the partner feed
* `meta.nextCursor` advances forward from the current page
* cursors remain usable if matching rows disappear between requests
* pagination reflects the current eligible set and is not a frozen snapshot
* historical list reads may default to a bounded time window when `startTime` and `endTime` are omitted
* historical list reads echo the applied bounds in `data.meta.appliedTimeRange`
* every list and stats read returns the server's current UTC time in `data.meta.serverTime`; anchor relative-time phrases on it

## Technical references

* [Available data reads](/guides/rest/data-reads)
* [Partner Feed guide](/guides/rest/feed)
* [Events documentation](/guides/rest/events)
* [Contract limits](/guides/agent-client-contract-limits)
* [API reference overview](/api-reference/overview)
* <code>[https://api.centaur.io/v2/docs](https://api.centaur.io/v2/docs)</code>
* <code>[https://api.centaur.io/v2/openapi.json](https://api.centaur.io/v2/openapi.json)</code>