Postman collection

The Machine API ships with a Postman collection generated automatically from the OpenAPI 3.1 spec. Import it once, then iterate on requests without typing curls by hand.

Download collectionPostman Collection v2.1.0 · JSON

What’s inside

• Every operation in openapi.yaml, grouped by tag (Games, Sessions, Transactions, Health)
• Body schemas pre-filled with example values
• Four collection variables for deployment, its derived API base, credentials and the current logical operation

Variable	Default	What to do
apiOrigin	https://api.aggregator.gg	Set the origin of the deployment authorized for your integration; API requests and root health probes use it
base_url	{{apiOrigin}}/v1	Derived Machine API base; keep the default when changing apiOrigin
apiKey	YOUR_ISSUED_API_KEY	Paste your real key (see Authentication)
idempotencyKey	Empty	Before a financial operation, set a new UUID once; reuse it with the same body for retries

Do not use {{$randomUUID}} directly as a retry key: it changes on each send. After an ambiguous timeout, reconcile the outcome before starting a new operation with a new key. See Idempotency. The collection does not generate or rotate this value automatically.

Import

Postman

1. Postman → File → Import → drag the downloaded JSON
2. The collection appears under your workspace
3. Open the collection’s Variables tab, confirm apiOrigin, and set your issued apiKey. /health and /ready are unauthenticated root probes; they do not use /v1 or the key.
4. For an operation requiring Idempotency-Key, generate a UUID and set idempotencyKey before sending. Keep that value and request body for every retry of the same operation. Set a different UUID only when starting a different logical operation.
5. Review and replace generated example values with authorized players, catalog IDs and request parameters. An ordinary operator key must omit platform-only fields such as sub_operator_ref; use them only where the API contract and your credential permit them.
6. Send the configured operation permitted for the issued credential.

Insomnia

1. Insomnia → Application Menu → Import → choose From File → pick the JSON
2. Update the environment variables in the Manage Environments dialog

Hurl / Bruno / other tools

The collection is JSON in the standard Postman v2.1 format. Most modern API clients import it directly.

How it’s built

Every CI build of docs.aggregator.gg regenerates the collection from openapi/aggregator.yaml via the openapi-to-postmanv2 converter. The download URL is stable — bookmark it.

The generation script lives at scripts/build-postman.mjs in the docs repo.

When the spec changes

Re-download the JSON. Postman does not auto-sync, so you should refresh the collection whenever we publish a Changelog entry that affects request or response shapes.