Suggestion Sets
Reading generated content, as a list or one set at a time.
List suggestion-sets
Lists your tenant's suggestion-sets, newest first, however they were generated. Every filter is optional, and filters combine with AND. origin is the one exception: it takes a comma-separated list and returns sets matching any of the values you list. Pass it once with commas — a repeated origin parameter is not supported.
Results are paged with a cursor. Take meta.next_cursor from a response and pass it back as cursor for the next page; it is null on the last page. The order is always newest first, and there is no total count.
A filter value that does not exist — including an unknown origin value — gives you an empty page rather than an error. An unknown filter parameter is rejected with 422.
What you can see depends on how you authenticate. A signed-in user sees the sets they generated, plus all ready-made (precompute) content, which everyone in the tenant can read. An access-token caller sees every set in the tenant, and can narrow to one user with created_by. Anything you cannot see is simply absent from the page — you never get a 403, and asking for another user's sets gives an empty page.
query Parameters
origin^[a-z_]+(,[a-z_]+)*$A comma-separated list of origins to match: precompute, steered, or the legacy refinement. A set matching any of the values you list is returned. Pass it once with commas — a repeated origin parameter is not supported.
Filtering on refinement returns only sets written before refinements moved into threads, and nothing at all on a tenant with no such history. To find refinements, read threads instead. An unknown value gives an empty page rather than an error.
segment_idReturn only sets for this segment.
A UUID, lower-case and hyphenated. Identifiers minted by this API are UUIDv7, so sorting them as strings happens to order them by creation time — the listings rely on that, which is why they need no sort parameter. Do not depend on it yourself, and do not read a timestamp out of an id: ids from other systems may be a different version, and the guarantee is not part of this contract.
use_case_idReturn only sets for this use-case.
A UUID, lower-case and hyphenated. Identifiers minted by this API are UUIDv7, so sorting them as strings happens to order them by creation time — the listings rely on that, which is why they need no sort parameter. Do not depend on it yourself, and do not read a timestamp out of an id: ids from other systems may be a different version, and the guarantee is not part of this contract.
created_byReturn only items created by this user. Naming a user whose items you cannot see gives an empty page.
A UUID, lower-case and hyphenated. Identifiers minted by this API are UUIDv7, so sorting them as strings happens to order them by creation time — the listings rely on that, which is why they need no sort parameter. Do not depend on it yourself, and do not read a timestamp out of an id: ids from other systems may be a different version, and the guarantee is not part of this contract.
cursorThe meta.next_cursor value from a previous response. Treat it as an opaque string: pass it back unchanged, and never build one yourself.
limitHow many items to return per page. Omit it for 20. A value above 100 is rejected with 422 rather than quietly reduced to it, so read the maximum from this parameter rather than probing for it.
Treat it as an upper bound, not a promise: a short page does not mean the listing has ended. Keep paging until meta.next_cursor is null.
List suggestion-sets › Responses
The matching page of suggestion-sets.
Pagination metadata. There is no total count and no page number — a listing is walked forwards with the cursor until next_cursor is null, and cannot be jumped into part-way.
Fetch a suggestion-set by id
A signed-in user can fetch a set they generated, or any ready-made (precompute) set. An access-token caller can fetch any set in the tenant. A set you cannot see returns 404, not 403.
path Parameters
suggestionSetIdA UUID, lower-case and hyphenated. Identifiers minted by this API are UUIDv7, so sorting them as strings happens to order them by creation time — the listings rely on that, which is why they need no sort parameter. Do not depend on it yourself, and do not read a timestamp out of an id: ids from other systems may be a different version, and the guarantee is not part of this contract.
Fetch a suggestion-set by id › Responses
The suggestion-set.
idA UUID, lower-case and hyphenated. Identifiers minted by this API are UUIDv7, so sorting them as strings happens to order them by creation time — the listings rely on that, which is why they need no sort parameter. Do not depend on it yourself, and do not read a timestamp out of an id: ids from other systems may be a different version, and the guarantee is not part of this contract.
Always set today; reserved to be null for future content that is not tied to a use-case.
locale^[a-z]{2,3}(-[A-Z]{2… · requiredA BCP 47 language tag. Content is generated and stored in one of two locales today, written as a bare language code with no region subtag: en or de. The pattern also admits a region subtag (en-GB) so that regional content can be added without a breaking change, but no such locale exists yet: a request naming one matches nothing, and no response carries one. Which locale your content is generated in comes from your tenant's settings; you do not choose it per request.
versionThe catalogue position of your tenant's ready-made (precompute) content for this segment, use case and locale, increasing each time that content is generated again. Null for content generated from your own instructions (steered) or from an edit (refinement), which has no place in that sequence.
created_atWhen the set was written, which is when its generation finished rather than when it was asked for. It is also what the listing is ordered by, newest first.
originHow the set was produced. precompute is your tenant's ready-made content, generated on a schedule. steered is a generation from your own instructions.
refinement is legacy and is no longer produced. An edit of an existing suggestion used to be wrapped in a set of its own holding a single variant; it now appends a turn to a thread instead, so a refinement writes no set and reports a suggestion_id rather than a suggestion_set_id. The value remains because sets written before that change still carry it and are still readable — handle it when reading, and expect no new set to arrive with it.
The user who asked for the generation. Null only for ready-made (precompute) content, which no individual user requested.
The generation run that produced this set; null for ready-made content, which has no run.
steering_textThe instructions the set was generated from; null unless origin is steered.
The set's variants, every one of them — a set is written complete, so this is never partially filled and never paginated. How many there are depends on how the set was generated: a brief produces the variant_count you asked for, while ready-made content produces a per-use-case count you do not control. Order is not guaranteed; sort by variant_no for a stable display order.