API reference

Authentication

Datorus uses HTTP Basic auth over the proxy gateway. Send your gateway username and password with every request; route the request through the gateway with your HTTP client's proxy option. New here? Start with the price-monitoring quickstart.

curl -x http://USERNAME:PASSWORD@gw.datorus.io:8001 \
     -L https://target.example.com/products

Endpoints

GETgw.datorus.io:8001 is the proxy gateway — point any HTTP client's proxy setting at it. Datorus relays your request to the destination and returns the upstream response unchanged. There is no Datorus REST API surface for the proxy itself; you talk to your target through the gateway.

Sessions

By default each connection gets a fresh upstream session. To reuse one upstream session across a multi-step flow, send a session id header.

Live: send X-Datorus-Session-Id — an opaque id you generate (allowed characters A–Z a–z 0–9 _ -, up to 128 chars) — to pin a multi-step flow to a stable upstream egress. The gateway honours the header, echoes the same id back on the response, and scopes the affinity to your account, so your id can never collide with another customer's session. An invalid or absent header falls back to the default per-connection session (it is never an error). The exact affinity window (TTL), rotation, and concurrency limits are being finalized in Phase 7 load testing — subscribe to the changelog for the published values.

Rate limits

Live: the gateway emits X-Datorus-RateLimit-Limit, X-Datorus-RateLimit-Remaining, and X-Datorus-RateLimit-Reset on every response, and a 429 includes a Retry-After header per RFC 7231. The per-credential limit is a soft limit while we finish Phase 7 load testing; the headers always reflect the limit currently in force. The final concrete numbers (requests/second, burst) ship after load testing — subscribe to the changelog for the published values.

Error responses

Every error uses one canonical JSON envelope. The machine-readable code is SCREAMING_SNAKE_CASE and is never translated; message is English-only; requestId is a UUID; timestamp is ISO 8601 UTC.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your balance is too low to complete this request.",
    "details": { "currentBalanceCents": 0, "requiredCents": 120 },
    "requestId": "0190f8c2-7a3b-4d8e-9f1c-2b5e8a4d6f01",
    "timestamp": "2026-05-19T14:32:18Z"
  }
}

The Example response column is the complete error envelope for each code (code + message + details + requestId + timestamp); requestId and timestamp vary per request. message is English-only regardless of locale.

Reserved headers

The Status column is honest about what the gateway sends today. These headers ride the HTTP forward response and the CONNECT 200 Connection established (both are proxy-layer headers the gateway controls); the inner tunneled HTTPS payload is end-to-end encrypted, so the proxy cannot add headers there.

Idempotency

Proxy requests are not idempotent by nature — they are forwarded to your target as sent. Billing top-ups use Stripe's idempotency keys internally so a retried checkout never double-charges.

Webhooks

Datorus does not deliver outbound webhooks for proxy traffic. Billing events are handled internally via Stripe; you do not need to host a webhook endpoint.

OpenAPI

A machine-readable OpenAPI description is planned. Until then, this page is the reference — subscribe to the changelog for updates.