Manage Content Plan

KEYWORD_RESEARCH means keyword research is complete and the job is waiting for the Create Content Plan request to generate the briefs. This request releases the intentional pause; polling alone does not advance it.

Use the selected site’s authorization context. Trigger and Create Content Plan are writes requiring Manage SEO Settings; execute them when the user has requested generation or explicitly confirmed it.

Resume or read an existing flow

An existing flow is a job already started by a previous trigger, including one discussed earlier in the conversation. To finish it or read its results:

1. Find its actual contentPlanFlowId in the conversation or a previous trigger/status response. A site ID is not a flow ID, even though both are UUIDs. If the ID is missing, explain the intentional pause when the user reports KEYWORD_RESEARCH, ask for the flow ID, and end the turn without an API call. Never submit a placeholder. Do not offer a new flow or a different site as an alternative to recovering the ID.
2. Read that flow with GET https://www.wixapis.com/promote/seo/v1/content-plan-flows/{contentPlanFlowId}. Read contentPlanFlow.status; see the response and status table in Check the flow status.
3. At SUCCESS, go directly to Read the briefs. At KEYWORD_RESEARCH, when completion is requested, call Create Content Plan once with this flow ID. For an earlier in-progress status, continue checking this same flow until it reaches the pause. If already at CONTENT_PLAN, continue to step 4 without calling Create Content Plan again. For a terminal or unmet-requirement status, follow the status table and stop.
4. After Create Content Plan succeeds, retain its returned flow ID and check until SUCCESS, then read the briefs. Do not trigger a replacement or release a successful flow just to retrieve its results.

Generate a new plan

When the user requests a new plan, follow these steps in order. The request and response examples for each step are in API steps.

1. Trigger once and retain the returned flow ID.
2. Check the flow status until KEYWORD_RESEARCH.
3. Call Create Content Plan once to continue generation.
4. Check until SUCCESS.
5. Read the briefs and report the actual returned topics.

Only Trigger and Create Content Plan write data in the generation path. Do not change the site’s business profile, name, description, categories, or publication state to accelerate it. Those are separate tasks requiring real user data and authorization. CREATED can mean queued work, not missing setup.

Polling without losing progress

One API execution makes one HTTP request and returns. The sequence below is a series of separate calls, with a decision after each response. It is not one code block containing the entire workflow. Never wrap API calls in a for/while loop, a timer, or a function that polls until a target status.

Retain each response’s flow ID before the next call. Wait between status checks using the client’s supported waiting capability, outside the API execution; do not assume timers exist inside that execution or busy-wait there.

Keep checking while work progresses. If waiting cannot continue, report the flow ID and last observed status as incomplete; do not claim success or merely promise to finish later. Identify trigger and release as writes if asked whether an execution changes data.

API steps

1. Trigger

Response:

<flow-uuid> and other angle-bracket values in these examples are placeholders; substitute actual returned values before making requests. Return this response and end this execution here. Save the ID before making any status request. Do not append step 2 to the trigger script. See Trigger Content Plan Generation Flow (opens in a new tab).

2. Poll until KEYWORD_RESEARCH

Execute this GET once and return its response. This execution contains no for/while loop and no timer. Repeat it as a separate call when another status check is needed. Keep the response compact: flow ID and status suffice.

Example response, showing the public flow fields (optional fields may be absent):

Read contentPlanFlow.status, not a top-level status. If it is missing, inspect the response instead of silently looping. Always use this generation’s flow ID; if it stays CREATED, report the ID and observed status without inventing missing business prerequisites. See Get Content Plan Flow (opens in a new tab).

contentPlanFlow.status is a string enum. Status checks may skip intermediate states; decide from the returned value rather than requiring every transition. Typical status progression: CREATED → SITE_ANALYSIS → KEYWORD_RESEARCH → call Create Content Plan → CONTENT_PLAN → SUCCESS.

Check every few seconds using separate calls. Completion time varies.

3. Release the flow

Successful response:

Failure response fields (the diagnostic text comes from the API):

The response fields are success (boolean), message (failure reason, only when success is false), and contentPlanFlowId (flow UUID when returned). Check success as well as the HTTP status. If false, report message and stop; a successful HTTP response alone is not a completed plan.

On success, retain the returned contentPlanFlowId for the next status check and candidate read. This response is not the list of briefs: continue to steps 4 and 5. Do not call release again to retrieve results; on an already successful flow it regenerates a plan under a new flow ID. See Create Content Plan (opens in a new tab).

4. Poll until SUCCESS

Same single-GET execution and nested response as step 2, using the release response’s flow ID and returning after each check. Typical status progression: CONTENT_PLAN → SUCCESS. Read candidates in a subsequent execution after observing SUCCESS.

5. Read the briefs

Example response showing the fields needed to display one topic:

This is illustrative data, not the user’s results. Candidates can contain additional fields; see the linked reference for the full contract. Omitting paging returns all candidates in a single response. Each candidate’s brief fields are nested under briefData, not at the candidate’s top level. Map them directly:

pageUrl identifies the existing site page the proposed post supports; it is not the URL of a newly published blog post. Generation creates briefs, not published posts. Do not read candidate.title, candidate.keyword, or candidate.pageUrl, or infer missing data from those nonexistent top-level fields. If a nested field is absent, report it as unavailable and inspect the raw candidate before making another request. Report the actual returned titles and available keywords/supporting page URLs. Do not invent briefs or claim completion from the release response. See List Blog Post Candidates (opens in a new tab).

Present the result

Start with the flow ID, observed SUCCESS status, and returned candidate count. Use a compact table with one row per topic: suggested title, target keyword, main keyword, and supporting page URL. Include the actual returned URL as a link; do not merely say that each brief contains a URL. Avoid repeating SEO titles and descriptions unless requested. If the answer must be shortened, label the displayed subset and total explicitly instead of claiming to show all topics. These are AI-generated suggestions; do not promise rankings or traffic. Assess the returned topics before recommending them: if they are repetitive, mostly restate the site name, or lack a clear connection to the site’s business, say so plainly. Successful generation does not establish editorial quality. Still show the actual results; do not silently replace weak titles with invented ones or call them optimized without evidence. Explain what business context would help assess or refine them, without modifying the site’s settings.

Editing keywords (optional)

After step 2, before or after step 3, read the keywords:

Edit one keyword (field-masked, only keyword and main_keyword writable):

Copy-on-write: the response may carry a different keywordResearchId. Always use the one from the response for the next write. Edits are not durable across generations.

Do not

• Poll forever without calling Create Content Plan (step 3).
• Read candidates before SUCCESS.
• Retry after PENDING_REQUIREMENTS.
• Ask for a site ID.
• Retry after a 403 — the caller lacks Manage SEO Settings.