Requests
Postforge API conventions for URLs, JSON bodies, money, dates, ids, pagination, search, filters and sorting.
URLs and resources
The API lives at https://api.postforge.dev/v1. Resources are plural nouns
(/v1/orders, /v1/orders/{id}); actions are verbs below a resource with POST
(/v1/product-priority-changes/{id}/apply). An operation a resource doesn't support doesn't exist.
Bodies
- JSON in and out, property names in camelCase.
- Money is an object in minor units with its ISO 4217 currency:
{ "amount": 4950, "currency": "EUR" }is €49.50. - Timestamps are ISO 8601 in UTC:
2026-10-16T09:30:00.000Z. - Ids are UUIDv7 strings. An id that doesn't exist, or belongs to another workspace, answers
404. - Locales are full BCP 47 locales, a language and a country:
nl-NL,en-US, neveren.
Lists
Every list takes the same query parameters:
| Parameter | Meaning |
|---|---|
page | Page number, starting at 1 |
pageSize | 10, 25 (default), 50 or 100 |
q | Search text |
sort | A sort key, - in front for descending: sort=-placedAt |
Filters are named per list and take comma-separated values: payment=paid,refunded. An unknown
value is a validation problem, never silently ignored.
The answer is a page:
{ "items": [], "total": 128, "page": 2, "pageSize": 25, "all": 412 }total counts what matches the search and filters; top-level lists also give all, the count
before them. A record's small sub-collections (a profile's merges) answer { "items": [] }.
Large exports and imports are jobs you start and then read, not pages.
Writes
Send Content-Type: application/json and an Idempotency-Key.
Creates answer 201 with the record; changes answer 200; deletes answer 204.