Synup
Create a key
v1Resources/AEO/postAdd tracked prompts to a website

Add tracked prompts to a website

Adds prompts to a website's tracked set as active prompts: 1 to 50 per request, each up to 500 characters. At most 16 prompts can be active at once; a request that would go over is 409 prompt_limit and saves nothing. Each line is trimmed and its whitespace collapsed. A blank or too-long line is 400 invalid_input; a line repeating a current prompt (ignoring case and spacing) or another line of the request is reported in issues, as 409 duplicate_prompt when every problem is a duplicate. Saving only changes what the next check measures: it never starts, buys or reschedules a check, spends no credits and leaves the schedule as it is. Needs the Manage AEO prompts permission — owners and admins hold it, other members only when it was granted to them (403 forbidden otherwise) — and prompt management switched on for the agency (403 feature_disabled otherwise). Answers 201 with the new prompt ids, or 200 when it replays an earlier request with the same mutationId. An unexpected failure is 503 prompts_unavailable.

post/api/v1/aeo/prompts
aeo:write
Request body
locationIdstringrequired
The website entity's location id. A website you can't see, or one that doesn't exist, is 404; a physical location is 422 entity_type_not_supported.
textsarray of stringrequired
The prompts to add, one per item: 1 to 50 per request, each 1 to 500 characters after trimming. They are added as active prompts after the existing ones.
expectedRevisionintegerrequired
The set revision you last read (revision in the list view). The change is applied only if it still matches; otherwise it is 409 prompt_set_changed with latestRevision, so you can read the set again and decide.
mutationIdstringrequired
Your id for this change: 8 to 100 letters, digits, _ or -. On DELETE, send it as the Idempotency-Key header. Once a change is saved under an id, repeating the same request returns replayed true and the current view without applying it again, and reusing that id for a different request is 409 mutation_reused. A request that changed nothing stores no id: repeating it is decided again against the current revision (noop true, or 409 prompt_set_changed if the set has moved on). If you don't know whether a write landed, retry with the same id, or read the list and reconcile, before sending a new id.
Response
dataobjectoptional
viewobjectoptional
locationIdstringoptional
The website entity's location id.
namestringoptional
The website's name.
eligibleboolean (true)optional
Always true: only a website entity has a tracked prompt list.
canEditbooleanoptional
Whether the token's issuing person can change this set right now: they hold the Manage AEO prompts permission, prompt management is switched on for the agency, and the earlier prompt list needs no reconciliation.
managedbooleanoptional
false while the website still uses its cached existing prompt list (shown as imported prompts of unknown provenance); true from the first saved change.
revisionintegeroptional
The set's revision, raised by every saved change. Send it as expectedRevision, or in If-Match on DELETE.
maxActiveintegeroptional
The most prompts that can be active at once (16).
maxLengthintegeroptional
The longest a prompt may be, in characters (500).
countsobjectoptional
Number of active and paused prompts.
activeintegeroptional
pausedintegeroptional
itemsarray of objectoptional
The prompts in set order, filtered by the status parameter.
idstringoptional
Unique identifier for the prompt.
textstringoptional
The prompt's wording. In a check or history entry, the wording that check measured.
normalizedTextstringoptional
The wording trimmed, whitespace collapsed and lowercased: the key used to detect duplicates.
wordingVersionintegeroptional
The wording's version: 1 when created, one higher after every wording change. Send it back as expectedWordingVersion.
statusstring (active | paused)optional
active (measured by the next check) or paused (kept, but left out of checks).
originstring (existing | custom | generated | integration)optional
Where the prompt came from: existing (imported from the website's earlier prompt list, provenance unknown), custom (added in the app), generated, or integration (added through the API or MCP).
createdViastring (ui | api | mcp | import)optional
How the prompt was created: ui, api, mcp, or import.
createdByUserIdstringoptional
The person who created the prompt, or null when unknown (imported prompts).
updatedByUserIdstringoptional
The person who last changed the prompt, or null when unknown.
positionintegeroptional
The prompt's place in the set's order.
createdAtstringoptional
When the prompt was created, as an ISO 8601 timestamp.
updatedAtstringoptional
When the prompt was last changed, as an ISO 8601 timestamp.
deletedAtstringoptional
When the prompt was removed, or null. Removed prompts are not listed but stay in the checks that captured them.
latestobjectoptional
The latest usable result for the current wording, from a settled complete, partial or failed check, or from a provably matching imported legacy wording: state checked with at, measured and expected. A held check stays in history and does not advance it. Otherwise state not_checked, including right after an edit.
editedbooleanoptional
Whether the wording has changed since the prompt was created.
workloadobjectoptional
Approximately what one check of the active prompts involves. Reading it costs nothing, and saving prompts spends no credits.
activePromptsintegeroptional
Active prompts the next check would measure.
enginesarray of stringoptional
The AI engines a check queries.
answerChecksintegeroptional
Active prompts × engines: the answers one check asks for. A count, not credits.
estimatedCreditsnumberoptional
Approximate credits for one check of the active prompts, from your agency's credit rates. null when the rate is unknown or more than 16 prompts are active — unknown, not zero. An estimate, not a charge.
creditsPerPromptnumberoptional
Approximate credits per prompt across all engines, or null when unknown.
approximateboolean (true)optional
Always true: the workload figures are estimates.
scheduleobjectoptional
The website's current AEO check schedule. Changing prompts does not change it.
frequencystring (weekly | monthly | quarterly | never)optional
How often checks run: weekly, monthly, quarterly, or never.
nextRunAtstringoptional
When the next scheduled check is due, as an ISO 8601 timestamp, or null when the frequency is never or checks haven't started for this website.
activatedbooleanoptional
Whether checks have started for this website (a first check was started or a report exists). Saving prompts does not start them.
checkInFlightbooleanoptional
Whether a check is queued, running or held for this website right now. That check keeps the prompts it captured; changes apply from the next one.
listChangedSinceReportbooleanoptional
Whether the active prompts differ from those the current report measured, so the report does not reflect the current list yet.
needsReconciliationbooleanoptional
Whether the website's earlier prompt list has malformed or duplicate entries. Until support reconciles it, changes are 409 legacy_prompts_need_reconciliation.
noopbooleanoptional
true when the request matched what was already stored and nothing was saved.
replayedbooleanoptional
true when this repeats a change already saved under the same mutationId; the change is not applied again and view is the current one.
createdIdsarray of stringoptional
Ids of the prompts this request added, in order. Empty for other changes and on a replay.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
409The request conflicts with the current state of the resource — for example, changing the email or phone of a recipient who has already been messaged, or a team invite that was already accepted (or hasn't been accepted yet).
422The request is missing a required parameter or is otherwise malformed.
429Too many requests. Retry after the number of seconds in the Retry-After header.
503The service is temporarily unavailable. Follow the retry guidance for this operation.
post/api/v1/aeo/prompts
Your API key
Request body*
{}

Guides that use this resource