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

# API Reference

> Pegana's live OpenAPI reference covers the annotated HTTP surface, including webhook operations, health checks, and metadata endpoints.

The endpoints listed in this tab are generated from the live OpenAPI spec at
[api.pegana.xyz/openapi.json](https://api.pegana.xyz/openapi.json).
Use the **try-it-now** panel on each endpoint to send a real request.

<Note>
  The OpenAPI spec is assembled from utoipa annotations on the axum handlers.
  Coverage is incremental; use the guides for endpoints that are not yet
  annotated.
</Note>

## Base URL

```
https://api.pegana.xyz
```

## Authentication

Most endpoints are **public** — no `Authorization` header required. The user-scoped
routes (anything under `/v1/me/*`, plus `/v1/auth/logout`) require a JWT obtained via
Telegram Login. See [authentication](/docs/authentication).

## Rate limit

Soft sliding window: **300 req/min per IP** on REST. WebSocket allows **5 concurrent
connections per IP**. Liveness / readiness probes are exempt.

Hit the limit? Email `raffxweb3@gmail.com`.

## Cross-origin

CORS allowed from `pegana.xyz`, `www.pegana.xyz`, `localhost:3000` by default.
Self-hosted instances can extend via `CORS_EXTRA_ORIGINS`.

## Errors

Standard HTTP codes. Error bodies are `{"error": "...", "message": "..."}` — short,
machine-readable.

## SDKs

There are no official SDKs yet — the API is small enough that direct HTTP calls are
recommended. For typed access in TypeScript, the OpenAPI spec drives codegen via
your favorite tool (orval, openapi-typescript, etc.).

## Quick links

<CardGroup cols={2}>
  <Card title="Read one state" icon="code" href="/docs/guides/rest-api">
    `GET /v1/assets/:asset/state` — the canonical read.
  </Card>

  <Card title="Stream live" icon="bolt" href="/docs/guides/websocket">
    `wss://api.pegana.xyz/v1/ws` — sub-second push.
  </Card>
</CardGroup>