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

# Discovery overview

> Search and filter series, events, and markets in the PolyOrderbooks catalog.

Discovery endpoints return metadata for markets in our catalog. Responses are served from local storage — not live Polymarket APIs — for predictable latency and consistent snapshots.

<Note>
  **Coverage:** We currently index Polymarket **crypto** markets. Markets in other categories are not included in the hosted catalog yet.
</Note>

## Endpoints

| Method | Path                       | Description                              |
| ------ | -------------------------- | ---------------------------------------- |
| `GET`  | `/v1/series`               | Paginated series catalog                 |
| `GET`  | `/v1/events`               | Paginated events catalog                 |
| `GET`  | `/v1/markets`              | Paginated markets catalog                |
| `GET`  | `/v1/markets/{id_or_slug}` | Single market with outcomes and metadata |
| `GET`  | `/v1/tags`                 | Tag index with occurrence counts         |

All discovery routes require `X-API-Key` on the hosted API.

## Recommended workflow

```mermaid theme={null}
flowchart LR
  A[Search markets] --> B[Select id or slug]
  B --> C[Market detail]
  C --> D[Historical queries]
```

1. **Search** — `GET /v1/markets?search=bitcoin&limit=50`
2. **Select** — note `id` or `slug` from `data[]`
3. **Detail** — `GET /v1/markets/{slug}` for token ids and resolution state
4. **History** — query `/prices`, `/metrics`, or `/books` on the same identifier

## List response format

```json theme={null}
{
  "metadata": {
    "count": 50,
    "limit": 50,
    "next_cursor": "NTA="
  },
  "data": [
    {
      "id": "618831",
      "slug": "will-btc-hit-100k",
      "question": "Will BTC hit $100k?",
      "status": "active",
      "volume": 1250000.0,
      "liquidity": 85000.0,
      "tokens": [
        { "id": "0xabc...", "label": "Yes" },
        { "id": "0xdef...", "label": "No" }
      ]
    }
  ]
}
```

When `metadata.next_cursor` is non-null, pass it as the `cursor` query parameter. See [Pagination](/historical/pagination).

## Query parameters

### Shared filters

| Parameter                | Endpoints               | Description                                          |
| ------------------------ | ----------------------- | ---------------------------------------------------- |
| `search`                 | series, events, markets | Case-insensitive full-text search                    |
| `limit`                  | all lists               | Page size — default `100`, max `1000`                |
| `cursor`                 | all lists               | Opaque pagination token from `metadata.next_cursor`  |
| `tags`                   | series, events, markets | Comma-separated tag slugs                            |
| `tags_match`             | series, events, markets | `any` (default) or `all`                             |
| `start_date_min` / `max` | all lists               | Filter by start date (ISO date or timestamp)         |
| `end_date_min` / `max`   | all lists               | Filter by end date (ISO date or timestamp)           |
| `sort`                   | all lists               | `updated_at`, `created_at`, `start_date`, `end_date` |
| `order`                  | all lists               | `asc` or `desc`                                      |

### Relationship filters

| Parameter                  | Endpoint | Description                        |
| -------------------------- | -------- | ---------------------------------- |
| `series_id`, `series_slug` | events   | Scope events to a parent series    |
| `event_id`, `event_slug`   | markets  | Scope markets to a parent event    |
| `include_closed`           | markets  | Include closed markets when `true` |

## Market identifiers

`{id_or_slug}` accepts:

* Source market id (e.g. `618831`)
* URL slug (e.g. `will-btc-hit-100k`)
* Scoped public id (e.g. `polymarket:market:618831`)

## Example

```bash theme={null}
curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets?search=eth&limit=5&sort=updated_at&order=desc" \
  | jq '.data[] | {slug, question, status, volume}'
```