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

# API Reference

> Complete reference for the poly-data REST API

## Base URL

All API requests should be made to:

```
http://api.poly-data.xyz
```

## Authentication

The poly-data API is currently **open access** — no authentication required.

## Rate Limits

To ensure fair usage, the API enforces rate limits per IP address:

| Scope                      | Limit       | Window   |
| -------------------------- | ----------- | -------- |
| **Global (all endpoints)** | 60 requests | 1 minute |
| **Orderbooks endpoints**   | 30 requests | 1 minute |

Rate limit headers are included in every response:

| Header                | Description                          |
| --------------------- | ------------------------------------ |
| `RateLimit-Limit`     | Maximum requests allowed             |
| `RateLimit-Remaining` | Requests remaining in current window |
| `RateLimit-Reset`     | Unix timestamp when the limit resets |

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response.

## Pagination

The API supports two pagination methods on most list endpoints.

### Cursor-based (Recommended)

Use the `next` object returned in responses for efficient pagination through large datasets. Each endpoint uses different cursor fields depending on its sort order.

```bash theme={null}
# First request
curl "http://api.poly-data.xyz/events?limit=50"

# Next page (using cursor values from response)
curl "http://api.poly-data.xyz/events?limit=50&cursor_end_date=1735689600000&cursor_id=12345"
```

### Offset-based

Traditional offset pagination is available but less efficient for large datasets:

```bash theme={null}
curl "http://api.poly-data.xyz/events?limit=50&offset=100"
```

<Warning>
  Cursor-based and offset-based pagination are mutually exclusive. If `offset` is provided, cursor parameters are ignored.
</Warning>

## Response Format

All responses are JSON. Successful list responses include the data array and pagination info. Errors follow this format:

```json theme={null}
{
  "error": "Error message description"
}
```

## HTTP Status Codes

| Status Code | Description                                 |
| ----------- | ------------------------------------------- |
| `200`       | Success                                     |
| `400`       | Bad request (missing or invalid parameters) |
| `404`       | Resource not found                          |
| `429`       | Rate limit exceeded                         |
| `500`       | Internal server error                       |

## Caching

Responses are cached briefly server-side to improve performance:

| Endpoint                  | Cache TTL |
| ------------------------- | --------- |
| List and search endpoints | 2 seconds |
| Single resource endpoints | 5 seconds |
| `/orderbooks/latest`      | 500ms     |

## Endpoints Overview

<Columns cols={2}>
  <Card title="Events" icon="calendar" href="/api-reference/events">
    Search and list prediction market events.
  </Card>

  <Card title="Markets" icon="store" href="/api-reference/markets">
    Get market details and token information.
  </Card>

  <Card title="Orderbooks" icon="book" href="/api-reference/orderbooks">
    Access historical orderbook snapshots.
  </Card>

  <Card title="Statistics" icon="chart-pie" href="/api-reference/statistics">
    Database size and system statistics.
  </Card>
</Columns>

## Health Check

Verify the API is operational:

```bash theme={null}
curl "http://api.poly-data.xyz/health"
```

Response:

```json theme={null}
{
  "status": "ok",
  "time": "2026-01-23T12:00:00.000Z"
}
```