# Lumi API (proxy)

> Buy and manage Lumi proxies from your own code: residential and mobile traffic,

Authentication: send `Authorization: Bearer <key>` on every request. A key belongs to one account and can only see and spend on that account. Keys are issued by Lumi support (@lumisup_robot) on request.

## Documents

- [Full API reference](https://api.lumiweb.cc/proxy/llms-full.txt): every endpoint, parameter and error code in markdown - fetch this one to answer questions.
- [OpenAPI schema](https://api.lumiweb.cc/proxy/openapi.json): machine-readable, use it to generate a client or tool definitions.
- [Interactive docs](https://api.lumiweb.cc/proxy/docs): the same schema with a "try it" console for humans.

## Rules that apply to every call

- Base URL: `https://api.lumiweb.cc/proxy/v1`
- Start with `GET /v1/users/me`: it proves the key works and returns the balance and the key's limits.
- Money-moving calls need an `Idempotency-Key` header; retrying with the same key returns the first outcome instead of charging twice. Reusing a key for a different request is refused (`idempotency_key_reused`).
- Add `?dry_run=true` to a money call to validate it and see the price without charging anything.
- Errors are always `{"error": {"code": "...", "message": "...", "request_id": "..."}}`; branch on `code`, never on the message text.
- Amounts are strings in USD. Never parse them as floats before arithmetic.
- `429` carries `Retry-After` in seconds. Respect it. `X-RateLimit-Remaining` shows what is left of the per-minute budget.

This document describes the proxy API only. Each Lumi product has its own API, its own key and its own base URL.