Skip to content
Sign in
Menu

Understand API endpoints

How gateway URLs map to a provider's paths, which methods and headers pass through, and what comes back.

On this page

The gateway URL

Every API has one gateway URL, {gateway origin}/v1/{slug}. Add the provider's own path and query after it:

TextIllustrative values
https://gateway.example.com/v1/weather-forecasts                     → the provider's base URL
https://gateway.example.com/v1/weather-forecasts/forecast?city=Lisbon → {base}/forecast?city=Lisbon

Paths, parameters and bodies

NODRA passes your path, query string and body to the provider unchanged. The directory doesn't list a provider's individual paths, parameters or response formats yet: use the API's description, and the provider's own documentation where they link to it. Calling a path the provider doesn't serve usually gets an error, which isn't charged.

Path segments . and .. are refused with 400 invalid_path. Request bodies over 1 MiB get 413 request_too_large.

Methods

The gateway accepts GET, POST, PUT, PATCH and DELETE unless an API narrows the list; the directory's methods field shows it, and null means all five. Other methods, including HEAD and OPTIONS, get 405 method_not_allowed with an Allow header.

Headers

DirectionWhat passes through
Your request → providerContent-Type and Accept only. Your Authorization, cookies and payment headers are never forwarded.
Provider → your responseContent-Type and Content-Language, plus Cache-Control: no-store from the gateway.
Gateway → youPAYMENT-REQUIRED on a 402; PAYMENT-RESPONSE on a paid answer.

Authentication

You don't authenticate to the provider: NODRA adds the provider's key to the forwarded request. The payment is the only thing you send.

Pricing

Every path and method of an API costs the same. Each call needs its own quote and payment.

Responses

A paid, billable call returns the provider's status code and body. The gateway waits up to 20 seconds for the provider, and caps the provider's answer at 1 MiB. When a call isn't billable, you get a gateway error instead of the provider's body; see Error handling.