relayted API

Documentation

relayted API

Base URL https://api.relayted.de/v1 · JSON in, JSON out · one key for all services.

Quick start

  1. Create a key and top up at API key & balance.
  2. Create a job. With ?wait=20 the call returns as soon as the job is finished (at most 25 seconds are honoured).
  3. Download the results from the url of each result, with the same key.
export RELAYTED_KEY="RAPI-XXXX-XXXX-XXXX-XXXX-XXXX"

# 1. create a job and wait for it
curl -s "https://api.relayted.de/v1/websitepro/jobs?wait=20" \
  -H "Authorization: Bearer $RELAYTED_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","outputs":["markdown","metadata"]}'

# 2. fetch a result (the "url" field of the result)
curl -s "https://api.relayted.de/v1/jobs/JOB_ID/results/markdown" -H "Authorization: Bearer $RELAYTED_KEY"

Authentication

Send your key with every request to /v1 that touches your balance:

Authorization: Bearer RAPI-XXXX-XXXX-XXXX-XXXX-XXXX

Jobs & results

Every service follows the same pattern.

POST/v1/<service>/quote validate and price a request, free
POST/v1/<service>/jobs[?wait=seconds] charge and start
GET/v1/jobs/<id>[?wait=seconds] state of a job
GET/v1/jobs/<id>/results/<key> one result file
GET/v1/jobs your recent jobs (?limit=1..100)

A job consists of results (one per output, screenshot or test module). Each result is billed, delivered and refunded on its own.

{
  "job": {
    "id": "Zq3...", "service": "websitepro", "target": "example.com",
    "status": "completed",              // queued | processing | completed | failed
    "cost": 65, "refunded": 0, "charged": 65,   // Payloads
    "createdAt": 1790000000000, "expiresAt": 1790086400000,
    "results": [
      { "key": "markdown", "status": "done", "price": 45, "refunded": false,
        "contentType": "text/markdown; charset=utf-8", "bytes": 5120,
        "url": "https://api.relayted.de/v1/jobs/Zq3.../results/markdown" },
      { "key": "metadata", "status": "done", "price": 20, "refunded": false, "url": "..." }
    ]
  },
  "balance": 49935
}

Billing & refunds

All amounts are in Payloads (1 EUR = 10000 Payloads). The price list is on the pricing page and at /v1/pricing.

GET/v1/balance { balance, unit, eur }
GET/v1/transactions ledger of your wallet, newest first (?before=id)

Top up by API

A program that can pay Lightning invoices can refill its own balance. The first key is still created in a browser.

POST/v1/topups { "eur": 5 }
GET/v1/topups/<id> poll until status is "paid"
curl -s https://api.relayted.de/v1/topups -H "Authorization: Bearer $RELAYTED_KEY" \
  -H "Content-Type: application/json" -d '{"eur": 5}'

{ "topup": { "id": "...", "status": "pending", "eur": 5, "payloads": 50000, "bonusPayloads": 0,
             "bolt11": "lnbc...", "sats": 7500, "expiresAt": 1790003600000 } }

Minimum 0.25 EUR, maximum 100.00 EUR per top-up. The balance is credited as soon as the payment is confirmed.

Errors

Errors use HTTP status codes and always this body. Branch on code; message is for humans and may change.

{ "error": { "code": "insufficient_funds", "message": "...", "needed": 2400, "balance": 400 } }
StatusCodeMeaning
400bad_request, bad_url, no_output, ...The request is not valid. The service pages list their codes. Nothing charged.
400blocked_address, unreachableThe target is private/local or does not answer. Nothing charged.
401unauthorizedKey missing or wrong.
402insufficient_fundsBalance too low. Includes needed, balance, topup.
404not_found, unknown_serviceNo such job, result or service (also: a job of another key).
409not_readyThe result is still being produced.
410expiredThe result was deleted after its retention period.
429rate_limited, relay_busyToo many requests. Retry later.
503service_unavailable, busyService down or queue full. Nothing charged, retry in a moment.

Limits & retention