API keys
An API key lets scripts and agents call LivePair endpoints without a browser session and without an x402 wallet. Calls bill your prepaid credit balance at list price — the same balance that powers agent chat and the private studio, topped up once at /billing.
- Format:
lp_+ 64 random characters. Shown once at creation — we store only a SHA-256 hash and can't recover it later. - Send it as
x-api-key: lp_…orAuthorization: Bearer lp_…. - Create/manage: Settings → API keys — name, expiry, enable/disable, delete, per-key request count and 30-day credit spend.
What a key can call
| Endpoint | Auth | Billing |
|---|---|---|
POST /v1/chat/completions | session cookie or API key | OpenAI-compatible SSE chat; debits credits by token usage |
POST /v1/agent/generate | x402 or API key | image/video generation, per-call price quoted from the body |
POST /v1/agent/chat | x402 or API key | OpenAI-compatible {model, messages, max_tokens} completion |
GET /v1/agent/balance | API key only | prepaid balance (USD + micro-USD) and the 10 most recent ledger entries — x402 wallets are anonymous, nothing to look up |
On the /v1/agent/* endpoints a valid key skips the 402 round-trip
entirely — the request runs and debits credits. If the provider call
fails after submission, the debit is refunded automatically. The x402
volume tiers (wallet-keyed) don't apply on the key rail — keys bill
list price.
Errors
| Status | Meaning |
|---|---|
401 | No credentials, or the key is invalid/expired/disabled. The error body includes manageKeys/sign-in links. |
402 | Key valid but the credit balance can't cover the call — body includes a topUp link. |
429 | Rate limit — /v1/agent/generate is 6/min and /v1/agent/chat is 30/min per key or payer. |
Lifecycle
- Expiry: set at creation (30/90/365 days or never); changeable later
on the key row. Expired keys return
KEY_EXPIRED— they can't be revived, create a new one. - Disable vs delete: disable is reversible; delete is immediate and
permanent (the row and hash are gone — calls fail with
KEY_NOT_FOUND). - Sharing: a key spends your balance. Treat it like a password — keep it server-side, never in a browser bundle or a repo.
- Abuse: keys are tied to your account; banned accounts' keys stop working.
Machine-readable
- OpenAPI 3.1 with the
x-api-key/Bearersecurity schemes:https://livepairai.com/v1/agent/openapi.json - Product manifest:
https://livepairai.com/v1/agent/manifest.json - Agent skill file:
https://livepairai.com/SKILL.md - MCP:
https://livepairai.com/mcp(thedocsresource contains this full guide in markdown for agents)