Skip to main content
The endpoints listed in this tab are generated from the live OpenAPI spec at api.pegana.xyz/openapi.json. Use the try-it-now panel on each endpoint to send a real request.
The OpenAPI spec is assembled from utoipa annotations on the axum handlers and covers the full /v1 surface (39 paths, enforced in CI). It’s the source of truth the first-party TypeScript and Python SDKs are generated from.

​
Base URL

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

​
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 rafael@pegana.xyz.

​
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

First-party typed clients — TypeScript (@peganahq/sdk-ts) and Python (pegana-sdk) — are generated from the OpenAPI spec above and cover every /v1 endpoint, plus a hand-written live-feed WebSocket helper (PegFeed / peg_feed).
Reads need no API key. Until then, generating your own typed client from openapi.json is a first-class path — it’s exactly how the first-party SDKs are built (openapi-typescript + openapi-fetch for TypeScript, openapi-python-client for Python; orval also works).

Read one state

GET /v1/assets/:asset/state — the canonical read.

Stream live

wss://api.pegana.xyz/v1/ws — sub-second push.