# relayted API

> One HTTP API for all relayted services: cross-browser screenshots (shots), web page to Markdown/text/metadata/HTML/PDF (websitepro), and Nostr relay tests (labs). Prepaid balance in "Payloads", topped up with Bitcoin Lightning. Pay per delivered item. No account, no subscription.

Base URL: https://api.relayted.de/v1
Auth: `Authorization: Bearer <API key>` (a human creates the key once at https://api.relayted.de/account; no API call creates keys)
Unit: Payload. 10000 Payloads = 1 EUR. Current prices as JSON: https://api.relayted.de/v1/pricing
OpenAPI: https://api.relayted.de/openapi.json

## How every service works

1. Optional: `POST /v1/<service>/quote` with the same body as a job. Free. Returns `cost` (Payloads), `sufficient`, and the list of items.
2. `POST /v1/<service>/jobs?wait=20` charges the balance and starts the job. With `wait` (max 25 s) the call returns when the job is finished or the time is over.
3. If `job.status` is still `queued` or `processing`: `GET /v1/jobs/<id>?wait=20` until it is `completed` or `failed`.
4. Each entry of `job.results` with `status: "done"` has a `url`. GET it with the same Authorization header to download the file.

Billing rules: the whole job is charged at creation; every result that is not delivered is refunded automatically; rejected requests cost nothing. Responses contain `cost`, `refunded`, `charged` and the new `balance`.

Errors: HTTP status + `{"error":{"code":"...","message":"..."}}`. Branch on `code`.
- 401 unauthorized: key missing/wrong
- 402 insufficient_funds: includes `needed` and `balance`; top up, then retry
- 400 with a specific code (bad_url, blocked_address, unreachable, no_output, unknown_browser, bad_viewport, bad_relay_url, bad_port, no_checks ...): fix the request
- 404 not_found / unknown_service, 409 not_ready, 410 expired (result deleted)
- 429 rate_limited / relay_busy: wait and retry
- 503 service_unavailable / busy: nothing charged, retry later

## websitepro: web page -> Markdown, text, metadata, HTML, PDF

POST https://api.relayted.de/v1/websitepro/jobs
Body: {"url": "https://example.com/page", "outputs": ["markdown"]}
outputs: any of "metadata" (JSON), "markdown", "text", "html" (sanitised), "pdf". One result per output, key = output name.
Results kept 24 h. Docs: https://api.relayted.de/docs/websitepro

## shots: screenshots in real browsers

POST https://api.relayted.de/v1/shots/jobs
Body: {"url": "https://example.com", "browsers": ["chrome", "firefox"], "viewports": ["1920x1080"], "schemes": ["light", "dark"], "options": {"fullPage": true}}
- browsers: ids from GET https://api.relayted.de/v1/services/shots (no key needed). A string means the newest version; {"id": "chrome", "versions": ["131"]} picks versions.
- viewports (desktop browsers, max 3): "WIDTHxHEIGHT", a preset id (fhd, qhd, laptop, hd, tablet, phone) or {"w": 1280, "h": 800}. Default 1920x1080.
- schemes: "light", "dark". Default ["light"].
- options: fullPage, retina, hideCookieBanner (booleans), delay (0, 2 or 5 seconds).
One result (PNG) per browser version x viewport x scheme; key = file name. Add `?thumb=1` to a result URL for a small WebP. `GET /v1/jobs/<id>/zip` returns all finished screenshots once the job is completed.
Results kept 24 h. Docs: https://api.relayted.de/docs/shots

## labs: Nostr relay tests

POST https://api.relayted.de/v1/labs/jobs
Body: {"relay": "wss://relay.example.com", "modules": ["quick"]}
- modules: "quick" (connectivity, TLS, NIP-11, publish/query, latency, stability), "conformance" (NIP-01, all filters, event semantics, limits).
- checks: optional array of single check ids from GET https://api.relayted.de/v1/services/labs (field `selectable`); gives one result with key "custom". If a selected check needs the test dataset, the first such job of a wallet also carries a one-time fee as result "dataset" ("oneTime": true, no file); later jobs do not. The quote shows it.
- webhook: optional https URL that receives the finished reports.
Each result is a JSON report (schema "relaylab.report/1") with per-check status pass/fail/warn/skip/info.
A relay can be tested only a few times per hour (429 relay_busy). Reports kept 30 days. Docs: https://api.relayted.de/docs/labs

## Wallet

- GET /v1/balance -> {"balance": 49880, "unit": "Payload", "eur": 4.988}
- GET /v1/transactions -> ledger, newest first
- POST /v1/topups {"eur": 5} -> {"topup": {"id", "bolt11", "sats", "payloads", "status": "pending"}}; pay the Lightning invoice, then GET /v1/topups/<id> until status is "paid". Min 0.25 EUR, max 100.00 EUR.

## Limits

600 jobs per hour and key. Request bodies up to 64 KB. Only public targets (no private or local addresses).