API General API

FonProxy API General API reference documentation.

Base URL: https://api.fonproxy.io

Authentication

All protected endpoints require an API key:

Method	Header/Param	Example
API Key (header)	`x-api-key: <key>`	`x-api-key: fnp_3eab...`
API Key (query)	`?apikey=<key>`	`/api/v1/resource?apikey=fnp_3eab...`

Generate an API key in your account: API Keys.

The API uses the fp-locale header to determine the user's language.

fp-locale: uk

Every request: the backend reads fp-locale and uses it for server-rendered content (emails, Telegram notifications).
Logged-in users: if the header value differs from the stored locale, the backend automatically updates the user's locale in the database (fire-and-forget, no extra request needed).
Supported locales: en (English, default), uk (Ukrainian).
Fallback: if the header is missing or the locale is unknown, en is used.

Channel	Translated by	How
Email (subjects, body)	Backend	Translated before rendering to HTML
Telegram messages	Backend	Translated before sending
API error messages	Frontend	Backend returns raw keys (e.g. `order.not_found`), frontend translates
In-app notifications	Frontend	Backend stores raw keys in DB, frontend renders

The locale field is always returned in the user profile (GET /user/me) so the frontend can initialise its own i18n accordingly.

Header	Required	Description
`x-api-key`	Yes (protected routes)	API key for authentication
`fp-locale`	No	UI locale code (`en`, `uk`). Auto-synced to user profile.
`Content-Type`	Yes (POST/PATCH)	`application/json`

All responses are JSON. Success responses return the relevant data directly:

{
  "user": { "id": "k5Xz9qR2Wp", "name": "John", ... }
}

Error responses:

{
  "message": "order.not_found",
  "path": "/orders/80-12345",
  "timestamp": "2026-04-01T12:00:00.000Z"
}

The message field is a translation key — the frontend resolves it to a human-readable string.

Paginated endpoints accept:

Param	Default	Max	Description
`page`	`1`	—	Page number (1-based)
`limit`	`20`	`100`	Items per page

Response includes:

{
  "items": [ ... ],
  "total": 142,
  "page": 1,
  "pages": 8
}

All prices and balances are stored in USD internally.
Display values are converted using live exchange rates.
The user's preferred display currency is set via PATCH /user/settings { "currency": "UAH" }.
Endpoints that return monetary values include both *Usd and *Display fields.

Throttled by IP address. Default: 60 requests / minute for most endpoints, 5 / minute for auth endpoints.

When rate-limited, the API returns 429 Too Many Requests:

{ "message": "error.rate_limit" }