Making requests

JSON

Send JSON bodies with Content-Type: application/json (1 MB at most). Unknown fields and unknown query parameters are refused with 400 invalid_request, so a typo never passes silently.

Times are ISO 8601 in UTC, such as 2026-12-01T15:00:00Z. Ids are opaque strings; store them as they are.

Request ids

Every response carries a Request-Id header. Include it when you contact support; it finds the request in our logs.

Versions

Every response carries NOWScale-Version, the API version your key uses. Within a version, changes only add things: new endpoints, new optional fields, new event types and new error codes. Code that ignores unknown fields keeps working. See Versioning.

Pagination

List endpoints return pages, newest first unless the endpoint says otherwise:

{ "object": "list", "data": [ ... ], "has_more": true, "next_cursor": "WyIyMDI2LTEx..." }

Ask for the next page with ?cursor= and the next_cursor you received. limit takes 1 to 100 (25 by default). Cursors stay valid while new items arrive, so you never see an item twice.

curl "https://api.nowscale.com/v1/posts?limit=100&cursor=WyIyMDI2LTEx..." \
  -H "Authorization: Bearer $NOWSCALE_API_KEY"

Idempotency

POST endpoints that create something accept an Idempotency-Key header: any string up to 255 visible characters, unique per operation (a UUID is a good choice).

• The first request with a key runs, and its response is kept for 24 hours.
• A retry with the same key and the same body returns that response again, with Idempotent-Replayed: true. Nothing runs twice.
• The same key with a different body answers 422 idempotency_key_reused.
• A retry while the first request is still running answers 409 idempotency_in_flight; retry after a second.
• If the first request failed on our side (5xx), the key is free again and a retry runs normally.

Keys belong to the API key that sent them.

Errors

Errors are problem details with a stable code.