About the SEO APIs

The SEO APIs allow you to manage how a Wix site is found in search. They cover three jobs: the SEO tags a site's pages render, the content plan that decides what the site publishes next, and AI-generated suggestions for the text on a page.

The tag APIs read and write the titles, descriptions, social share tags, canonical links, structured data, and indexing directives that search engines and social networks read from a site's pages. Wix manages these tags at three levels, and there's an API for each one. Together they cover everything from a single page's title to a convention that applies across a whole site.

The content plan APIs work the other way around. Instead of describing pages a site already has, they research the keywords a site could rank for and turn them into briefs for blog posts to write.

The suggestion APIs generate text with AI: title tags, description tags, image alt text, heading levels, and whole-page rewrites. They return suggestions for you to review and apply, and don't change the site themselves.

The SEO APIs include:

• Site SEO Tags: Read and write the tags that apply to a site as a whole, such as its default social share image, whether search engines may index it, and the verification tags that prove ownership of the site to a search engine.
• SEO Patterns: Read and write the templates that generate tags for every item of a page type, such as every blog post or every store product. A pattern is written once and filled in with each item's own values when its page renders.
• Item SEO Tags: Read and write the tags of an individual item, such as a page, a blog post, or a store product, and see the tags an item is expected to render with, together with where each one came from.
• Content Plan Flow: Start a content plan for a site and follow its progress. Generation runs in the background and takes several minutes, so you trigger a flow and then poll it for its status.
• Content Plan Keyword Research: Read the site's current researched keywords, with their search volume and competition, and change which keyword a page targets. Reads are scoped to the site rather than to a flow: they resolve to the newest research that succeeded, whichever flow produced it.
• Content Plan Blog Post Candidates: Turn the researched keywords into blog post briefs, and read the briefs a flow produced.
• Tag Suggestions: Generate title tag, description tag, and image alt text suggestions for a page from content you pass in, and get the heading level each of a page's headings should have. Suggestions are returned per call and aren't stored.
• Page Optimization: Start a job that rewrites a site page's title tag, description tag, headings, and body text for the page's focus keyword, then poll for the before/after suggestions. Works on Wix-rendered sites only.

How the SEO tag APIs fit together

The tags a page renders with aren't stored in one place. Wix combines several sources, where a later source takes precedence:

1. The site's tags, from the Site SEO Tags API.
2. The pattern Wix provides for the page type.
3. The pattern the Wix user customized for that page type, from the SEO Patterns API.
4. The tags of the page that displays the item.
5. The tags of the item itself, from the Item SEO Tags API.

This means the same tag can come from any of three APIs, and the most specific one wins. Two practical consequences:

• Work at the level that matches the change. A convention for a whole page type belongs in a pattern; a value that differs for one item belongs on the item. Writing the same title onto a thousand items is the same outcome as one pattern, and much harder to undo.
• To see the result of the combination, read the item. The Item SEO Tags API returns resolvedTags for an item: the tags it's expected to render with, each marked with the source it came from. That's the only place the three levels are reported together.

Tags that site code, apps, or page components add while a page renders aren't part of this model, so resolvedTags isn't a literal copy of a page's rendered head.

How the content plan APIs fit together

The three content plan APIs are one sequence rather than three independent tools. A single flow carries a site from keywords to briefs, and each API owns one stage of it:

1. Start a flow with the Content Plan Flow API, then poll it.
2. Read the researched keywords with the Content Plan Keyword Research API once the flow reports the KEYWORD_RESEARCH status, and edit them if you want to.
3. Generate the briefs with the Content Plan Blog Post Candidates API, which also releases the flow to continue.
4. Poll the flow again until it reports SUCCESS, then read the briefs.

A flow doesn't run to completion on its own. It stops at KEYWORD_RESEARCH and waits, so an app that triggers a flow and only polls it waits indefinitely. Step 3 is what lets the flow finish.

SUCCESS isn't the only status a poll ends on, so treat the others as results rather than as a slow response:

• PENDING_REQUIREMENTS means the site is missing data the flow needs, and the flow resumes only once that data arrives. Polling alone never clears it.
• FAIL and CANCELED end that flow. A failed flow is retried under a new ID, so the ID you polled keeps its FAIL status even when a later attempt succeeds. Read the site's most recent successful flow instead of treating your own ID as the final answer.

The site keeps one current keyword research, and reads always resolve to the newest one that succeeded. A later generation therefore replaces what a read returns, including edits you made to an earlier copy. You can still edit keywords after a plan exists and generate again — each generation produces a new plan rather than changing the previous one.

How the suggestion APIs fit together

The two suggestion APIs produce text; the tag APIs store it. Tag Suggestions works from content you pass in the request, so it can serve any page, including a headless project. Page Optimization reads the page from the Wix site itself and needs the page's focus keyword set first, for example with the Item SEO Tags API. In both cases you review the suggestions, then write the ones you accept with the Item SEO Tags API or your own page code. Every suggestion call spends AI generation, so both APIs are rate limited per user.

Before you begin

These points apply to the three SEO tag APIs:

• Changes take effect on the live site without a site publish, with one exception: a static page keeps a draft separately from the published page, so tags written for one are saved to the draft unless you ask for them to be published.
• A write replaces what it targets in full. Retrieve the current tags or pattern first and send back the complete set you want, rather than only what changed.
• There's no revision checking. The last write wins, and a Wix user editing SEO settings in the dashboard writes to the same data. When someone may be editing at the same time, read immediately before writing.
• Coverage depends on which business solutions a site has. A page type or item type provided by a Wix business solution is only available on sites where that business solution is installed. Each API's errors list the types a site supports, so treat that as the current list rather than hard-coding one.

Terminology

• SEO tag: An element in a page's head that search engines and social networks read, such as a title, a meta description, a canonical link, or a block of structured data.
• Item: Anything on a site that has its own SEO tags, such as a page, a blog post, or a store product.
• Item type: The kind of item, such as STATIC_PAGE or STORES_PRODUCT.
• Page type: A category of page that shares a pattern, such as a store product page or a blog post page.
• Pattern: A template of SEO tags defined for one page type, whose variables are filled in per item.
• Variable: A placeholder such as {{product.name}}, written in double braces, that's replaced with an item's own value when its page renders.
• Resolved tags: The tags an item is expected to render with, after combining every source Wix manages.
• Focus keyword: The search term a page targets, set in its SEO settings. Page optimization suggestions are written to rank the page for it.
• Suggestion: AI-generated text for a page, returned for review and never applied automatically. Tag suggestions are single texts; page optimization suggestions are before/after pairs against the page's current text.
• Verification tag: A tag a search engine requires on a site to confirm that the person configuring it controls the site.
• Content plan: A set of blog post briefs built for a site from its pages, its business category, and search volume data. A content plan flow tracks the generation of one.
  • Keyword research: The keywords Wix researched for the site's pages during generation, each with its search volume and competition.
  • Blog post candidate: One brief in a content plan, proposing a blog post to write for a keyword.