v1Resources/AEO/patchEdit, pause or resume a tracked prompt
Edit, pause or resume a tracked prompt
Changes one prompt's wording, its status or both: send text, status or both, with expectedWordingVersion, expectedRevision and mutationId. Sending neither is 400 invalid_input. A wording change keeps the earlier wording and its results, and the new wording is measured from the next check as a new baseline. Pausing leaves the prompt out of future checks without removing it; resuming counts it against the 16 active prompts again (409 prompt_limit when that would go over). A request that matches what is stored saves nothing and answers noop true. Like every write it never starts or buys a check, leaves the schedule as it is and spends no credits, and it needs the Manage AEO prompts permission and prompt management switched on. An unknown or removed prompt is 404 prompt_not_found.
patch
aeo:write/api/v1/aeo/prompts/{promptId}Query parameters
promptIdstringrequired
The tracked prompt's id.
locationIdstringoptional
The website entity's location id, as a query parameter or in the body. The query parameter wins when both are sent.
Request body
locationIdstringoptional
The website entity's location id, as a query parameter or in the body. The query parameter wins when both are sent.
textstringoptional
New wording for the prompt, up to 500 characters. A real change creates a new wording version: the earlier wording and its results are kept, and the new wording is measured from the next check as a new baseline. Sending the current wording changes nothing.
statusstring (active | paused)optional
As a list filter: all (default), active or paused; any other value lists all. In an update: active to resume the prompt, paused to pause it. A paused prompt stays in the set but is left out of checks.
expectedWordingVersionintegerrequired
The prompt's wordingVersion as you last read it. If the wording has changed since, the update is 409 prompt_version_changed, which returns the current wordingVersion.
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.
patch/api/v1/aeo/prompts/{promptId}
Your API key
promptId *
locationId
Request body*
{}Guides that use this resource
- What Is a Local SEO API?A local SEO API measures how a business ranks in local search, with geo-grid rank tracking, profile analytics and AI visibility, not just backlinks.
- How to Add Local Marketing Features to Your SaaSAdd listings management, reviews, Google posts, profile analytics, rank tracking and AI visibility to a SaaS product with the Synup API, tenant by tenant.
- What Is an AEO API?An AEO API measures how AI answer engines like ChatGPT, Gemini and Perplexity describe and recommend a business, and tracks that visibility over time.
- How to Build an AI Agent for Local SEOBuild an AI agent that audits and fixes listings, tracks local rankings, checks AI visibility and drafts review replies with Synup's MCP server or REST tools.
- How to Build a Multi-Location Marketing DashboardBuild a multi-location marketing dashboard from the API's rollup endpoints, one call per panel, covering listings, reviews, rank, AI visibility and duplicates.
- Local SEO APIs: What Developers Actually NeedA practical checklist of what a local SEO API must cover, from listings and sync status to reviews, rank tracking and AI visibility, mapped to endpoints.
- How to Monitor Local SEO Across Multiple LocationsMonitor local SEO across hundreds of locations through rollup endpoints, with rank and AI visibility per location and the weakest surfaced first.
- How to Track AI and AEO Visibility ProgrammaticallyMeasure how ChatGPT, Gemini and Perplexity describe and recommend a business through an API, enqueue reports, poll for results and roll up a portfolio.