Suggestions
Reading a single suggestion.
Save content you wrote yourself
Saves a draft you wrote rather than generating one, so you can refine it afterwards exactly like generated content. It becomes the start of a refinement history, and a later refinement of it works the same way as refining any other suggestion.
Text only for now — a draft cannot carry an image, so only text kinds (email) are accepted. kind says which payload shape you are sending. The locale comes from your tenant's settings.
Signed-in users only, since every draft is attributed to the person who wrote it, and a machine-to-machine access token identifies an integration rather than a user.
An unknown segment or use case returns 404. A 403 means the capability is switched off for your tenant (steering_disabled). Draft text is checked before it is saved, and a rejection comes back as 422 with the same codes a rejected brief uses.
Save content you wrote yourself › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · kind="email" · requires: segment_id, use_case_id, payload |
kindsegment_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.
use_case_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.
Save content you wrote yourself › Responses
The draft was saved.
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.
The set this suggestion belongs to; null if it belongs to a thread but no set (a refinement).
kindTells you which payload shape to expect.
variant_noThis variant's position within its set; use it for a stable display order.
The suggestion this one was refined from, or null if it was not produced by a refinement.
rationaleWhy this content was suggested, or null when there is no explanation.
The content itself. Its shape is decided entirely by kind: email carries subject and body, social_single_image carries body and an asset. Switch on kind rather than probing for a property, and skip a suggestion whose kind you do not recognise — a future kind will bring a payload shape this list does not contain.
Text is plain text with real line breaks, not HTML or Markdown. Render it with the whitespace preserved; nothing in it is escaped for you.
The suggestions this one was refined from, closest first and the original last. Present only when you pass expand=lineage.
Fetch a single suggestion by id
Visibility follows the set the suggestion belongs to: a signed-in user can read suggestions from sets they generated and from ready-made (precompute) sets, and an access-token caller can read any suggestion in the tenant. A suggestion you cannot see returns 404, not 403.
Pass expand=lineage to include the earlier suggestions this one was refined from, closest first and the original last. Each entry is a short summary rather than a full suggestion.
path Parameters
suggestionIdA 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.
query Parameters
expand^lineage(,lineage)*$Pass lineage to include the suggestions this one was refined from. Any other value is rejected with 422.
Fetch a single suggestion by id › Responses
The suggestion.
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.
The set this suggestion belongs to; null if it belongs to a thread but no set (a refinement).
kindTells you which payload shape to expect.
variant_noThis variant's position within its set; use it for a stable display order.
The suggestion this one was refined from, or null if it was not produced by a refinement.
rationaleWhy this content was suggested, or null when there is no explanation.
The content itself. Its shape is decided entirely by kind: email carries subject and body, social_single_image carries body and an asset. Switch on kind rather than probing for a property, and skip a suggestion whose kind you do not recognise — a future kind will bring a payload shape this list does not contain.
Text is plain text with real line breaks, not HTML or Markdown. Render it with the whitespace preserved; nothing in it is escaped for you.
The suggestions this one was refined from, closest first and the original last. Present only when you pass expand=lineage.