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

# API Introduction

> Reference and usage patterns for the Monetary Public API

The API is documented from the OpenAPI schema in this repository:

<Card title="OpenAPI schema" icon="file-code" href="/docs/api-reference/openapi.json">
  View the source schema used to generate this API reference.
</Card>

## Endpoint groups

* `System`: `/` and `/health`
* `Companies`: `/v1/companies`
* `Prediction Markets`: `/v1/prediction_markets/events`, `/v1/prediction_markets/events/:id`, `/v1/prediction_markets/markets`, `/v1/prediction_markets/markets/:id`, `/v1/prediction_markets/similar_events`, `/v1/prediction_markets/trade_feed`
* `Realtime`: websocket subscriptions for event, market, and trade updates on the API service websocket path

## Auth requirements

* `Authorization: Bearer <token>` is required for all `/v1/*` endpoints.
* `/` and `/health` are public.

## Response envelope

Most list endpoints return:

```json theme={null}
{
  "data": [],
  "filters": {}
}
```

`filters` echoes normalized query parameters used by the backend (including defaults).

## Common status codes

* `200` success
* `400` validation error
* `401` missing/invalid bearer token (on `/v1/*`)
* `500` unexpected server error

## Caching

Successful `/v1/*` GET requests return:

```http theme={null}
Cache-Control: private, max-age=60, stale-while-revalidate=30
```

## Realtime updates

Use the websocket stream documented in [Realtime Stream](/docs/api-reference/endpoint/realtime-stream) when you need push updates for:

* event lifecycle changes: `created`, `updated`, `closed`
* market lifecycle changes: `created`, `updated`, `closed`
* standardized trade rebroadcasts from the live ingestion stream