# Making requests

> JSON in and out, request ids, versions, pagination and idempotency.

## 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](/versioning).

## Pagination

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

```json
{ "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.

```bash
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](/errors) with a stable `code`.