---
title: "Requests"
description: "JSON, pagination, idempotency keys, conditional writes, timestamps and money in the EZGH Cloud APIs."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Requests

## JSON

- Send request bodies as JSON objects with `Content-Type: application/json`.
- Field names are camelCase.
- Responses include every documented field. A field with no value is `null`, and an empty list
  is `[]`.
- Ignore response fields you don't recognize. New fields can be added at any time.

## Pagination

List operations are paged. [ListActions](/orgs-api/policies/ListActions/), which returns the
whole IAM action catalog, is the exception.

| Parameter | Meaning |
| --- | --- |
| `limit` | Items per page. 1 to 100, 20 by default, unless the operation's reference says otherwise. Out of range returns `400 invalid_request`. |
| `cursor` | The `nextCursor` from the previous page. Leave it out for the first page. |

The response holds the items in an array named for them, such as `projects`, and `nextCursor`,
which is `null` on the last page:

```json
{ "projects": [], "nextCursor": "eyJ2IjoxLCJvcmciOi…" }
```

- A page can hold fewer items than `limit`, or none, and still have a next page. Follow
  `nextCursor` until it's `null`; don't count items.
- A cursor works only with the list and filters it came from. Anything else returns
  `400 invalid_cursor`.

Trails pages differ: [LookupEvents](/trails-api/events/LookupEvents/) takes a `limit` up to 200
(50 by default), and [GetQueryResults](/trails-api/queries/GetQueryResults/) up to 1,000 (100 by
default).

## Idempotency keys

A create can be retried safely with an `Idempotency-Key` header. The operations that accept one
list it in the API reference, for example [CreateProject](/orgs-api/projects/CreateProject/) and
[CreateProcessor](/ocr-api/CreateProcessor/).

```sh
curl -X POST https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/projects \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c9e1a-2b3d-4c5e-8f60-718293a4b5c6" \
  -d '{ "name": "web" }'
```

- The key is 1 to 200 printable ASCII characters, without spaces. A UUID works.
- Retrying with the same key and the same request returns the first response again, with the
  header `Idempotent-Replayed: true`. Nothing is created twice.
- The same key with a different request returns `409 idempotency_conflict`.
- While the first request is still running, a retry returns `409 idempotency_in_progress` with
  `Retry-After`.
- Only successful responses are kept. Retrying a request that failed runs it again.
- Keys are kept for at least 24 hours, per organization. Keys for creating an organization are
  kept per user.

Operations without the header run again on every retry. [ProcessDocument](/ocr-api/ProcessDocument/)
is one: a retry processes the document, and bills for it, again.

## Conditional writes

Resources that clients read, change and write back answer `GET` with a strong `ETag` header, and
every write to them returns the new one. These include users, bots, groups and custom policies
in IAM, and OCR processors.

Send the `ETag` you read in `If-Match` on the write. If the resource changed since you read it,
the write returns `412 precondition_failed` and changes nothing: read it again and retry.
`If-Match` is optional; without it, the write applies to whatever is there. Weak tags
(`W/"…"`) never match. The operations that take `If-Match` list it in the API reference.

## Timestamps

- Responses give instants in UTC with milliseconds: `"2026-09-28T10:42:17.250Z"`.
- Requests take RFC 3339 timestamps with `Z` or an offset, to at most millisecond precision:
  `"2026-09-28T12:42:17+02:00"`.

## Numbers and money

- Money is a string of integer micros or cents, named in the field: `"amountDueMicros": "12500000"`
  is $12.50.
- Decimal quantities are strings, such as `"2537.25"`.
- Counts and limits are JSON numbers.

Parse money and decimals as exact decimals, not floating-point numbers.

Source: https://docs.ezghcloud.com/api/requests/index.mdx