Generator · Generic data
Draw an object from a weighted list of candidates
Endpoint GET /v1/object
What it covers
Returns a random object drawn from a user-supplied weighted list — a JSON array of `{ object, weight }` candidates in the `choices` param — returned verbatim. The object counterpart to `/v1/enum`. Weights need not sum to 1; they are normalized by their total. `choices` must be sent as URL-encoded JSON. An empty list, weights that are all zero / negative / non-finite, or a candidate whose serialized JSON is over-large, is a 400. `edge=true` inverts the distribution (Pro), `extreme=true` returns a hostile-encoded value (Pro), and `invalid=true` returns a sentinel object not among `choices` with probability 0.
The object counterpart to `enum`: draw a whole **JSON object** (or any JSON value) from a weighted set and get it back verbatim — for seeding a nested record whose variants follow a distribution you choose (a 5% “gold” customer object among 95% “free” ones).
Like `enum`, `choices` is URL-encoded JSON in two shapes. Pass a **bare array of candidates** for an equal split, or a **weighted list** of `{ "object": …, "weight": … }` entries to skew it. Weights are relative and normalized by their sum.
Gotchas
- The array is read as a *weighted list* only when EVERY entry is a `{ "object": …, "weight": … }` object; otherwise every entry is a literal candidate with weight 1. So a bare object that happens to have `object`/`weight` keys is still returned verbatim as long as the array isn’t uniformly weighted-shaped.
- Percent-encode the JSON in a real HTTP client (raw brackets only work in a browser address bar).
- An empty list, or a weighted list whose weights are all zero / negative / non-finite, is a 400.
Parameters
| Parameter | Type | Description |
|---|---|---|
| choices | string | URL-encoded JSON — either a weighted list [{"object":{"tier":"gold"},"weight":3},…] or a bare array of candidates [{"tier":"gold"},{"tier":"free"}] for an equal distribution. Weighted values are normalized by their sum. |
| count | integer1–1000 | Number of records to return, 1–1000 (your plan may lower this). Omitted returns a single record; set it for a batch. |
| edge | boolean | Invert the distribution: the least-probable candidate becomes the most likely (a zero-weight candidate rises to the top). Requires the Pro plan or above. |
| extreme | boolean | Return the drawn candidate with its string and number leaves wrapped in a hostile encoding (structure and booleans/null intact). Requires the Pro plan or above. |
| invalid | boolean | Return a sentinel object NOT among `choices` ({ __invalid__: true, token }), with probability 0 — for exercising unexpected-shape handling. |
| seed | integer | Integer seed for reproducible output: the same seed always yields the same record. |
Response fields
| Field | Type | Description |
|---|---|---|
| value? | object | The drawn candidate, returned verbatim. |
| probability | number | The candidate's weight normalized by the sum of all weights. |
Examples
GET /v1/object?choices=[{"tier":"gold"},{"tier":"free"}]GET /v1/object?choices=[{"object":{"tier":"gold"},"weight":3},{"object":{"tier":"free"},"weight":17}]GET /v1/object?choices=[42,[1,2,3],null,"text"]Other generic generators
Try it