# About the Site SEO Tags API

The Site SEO Tags API allows you to read and write the SEO tags that apply to a Wix site as a whole, rather than to one page. These are the tags a Wix user sets once and that appear across the site, such as the site's default social share image, whether search engines may index the site, and the verification tags that prove ownership of a site to a search engine.

With the Site SEO Tags API, you can:

- Retrieve the site's SEO tags, including any search engine verification tags.
- Set the site's default social share image.
- Control whether search engines may index the site.
- Set or clear the site's SEO tags.

## Site indexability and robots.txt

Two things control how search engines treat a site, and they do different jobs:

- **This API** controls whether a site may be **indexed**, using a `robots` tag with a `noindex` directive. Use it as the primary control over whether a site appears in search results.
- **The [robots.txt API](fallback::https://dev.wix.com/docs/api-reference/business-management/marketing/seo/txt-file-server/robots-txt/introduction)** controls how crawlers **crawl** a site.

Note that a page blocked from crawling in `robots.txt` can still be indexed, so blocking a crawler isn't a substitute for a `noindex` tag.

## Concurrent changes

The site's tags are a single set with no revision checking, and a Wix user editing SEO settings in the dashboard writes to the same tags as this API. If both change the tags at once, whichever lands second overwrites the other, with no conflict error. When a Wix user may be editing at the same time, retrieve the tags immediately before writing them.

## Before you begin

It's important to note the following points before starting to code:

- These tags are site-wide. To read or write the tags of an individual page or item, use the [Item SEO Tags API](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/introduction).
- **Setting `tags` replaces the site's tags in full.** Retrieve the current tags first and send back the complete set you want the site to have. Leaving out the `robots` tag makes the site indexable again, and leaving out `og:image` clears the site's default social share image.
- Verification tags returned in `embedTags` are read-only. Those are the tags a Wix user added through the site's SEO settings in the dashboard, which stores them as HTML embeds. Verification tags in `tags` are writable, and a site supports a single tag per provider.
- Changes take effect on the live site without a site publish.
- Site SEO tags aren't language specific. One set of tags applies to every language version of a site.

## Use cases

- [Verify site ownership with a search engine](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/sample-flows#verify-site-ownership-with-a-search-engine)
- [Take a site out of search results, then put it back](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/sample-flows#take-a-site-out-of-search-results-then-put-it-back)
- [Move a site's SEO configuration from another platform](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/sample-flows#move-a-sites-seo-configuration-from-another-platform)

## Terminology

- **Site SEO tags:** SEO tags that apply to the whole site rather than to one page.
- **Verification tag:** A tag a search engine requires on a site to confirm that the person configuring it controls the site. Also called a site ownership tag.
- **Embed tags:** Verification tags held as HTML embeds, in a separate store from the site's other tags. The live site renders them, but they're read-only here and are returned in `embedTags`.

@sdk_package_setup

# Site SEO Tags API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

## Verify site ownership with a search engine

A search engine confirms that someone controls a site before it will report that site's search data. One way to confirm it is a verification meta tag that the search engine provides, which must appear on the site.

Because setting `tags` replaces the site's tags in full, add the verification tag to the tags the site already has rather than sending it on its own.

To add a verification tag to a site:

1. Get the verification tag value from the search engine's console.
1. Call [Get Site SEO Tags](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/get-site-seo-tags) and keep the `tags` array from the response.
1. Append the verification tag to that array. For example:

    ```json
    {
      "type": "meta",
      "props": {
        "name": "google-site-verification",
        "content": "the-value-from-the-search-console"
      }
    }
    ```

1. Call [Set Site SEO Tags](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/set-site-seo-tags) with the combined array and `tags` in the `fieldMask`.
1. Ask the search engine to check the site.

A site supports a single verification tag per provider. Sending a second tag for the same provider replaces the first, so read the current tags before writing to see whether the site is already verified.

## Take a site out of search results, then put it back

While a site is being built or reorganized, a Wix user may not want it appearing in search results. Site indexability is controlled by a `robots` tag with a `noindex` directive.

To stop a site being indexed, then allow it again later:

1. Call [Get Site SEO Tags](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/get-site-seo-tags) and keep the `tags` array from the response.
1. Append a `robots` tag with a `noindex` directive to that array. For example:

    ```json
    {
      "type": "meta",
      "props": {
        "name": "robots",
        "content": "noindex"
      }
    }
    ```

1. Call [Set Site SEO Tags](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/set-site-seo-tags) with the combined array and `tags` in the `fieldMask`. The change takes effect on the live site without a site publish.
1. When the site is ready to be found, call [Get Site SEO Tags](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/get-site-seo-tags) again.
1. Remove the `robots` tag from the `tags` array, keeping every other tag.
1. Call [Set Site SEO Tags](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/set-site-seo-tags) with the remaining tags and `tags` in the `fieldMask`. With no `noindex` directive left, the site can be indexed again.

Removing the tag is what makes the site indexable, so send the full set of tags you want to keep. A request that omits tags the site still needs removes them too.

## Move a site's SEO configuration from another platform

When a site is rebuilt on Wix, its SEO configuration is spread across two levels: settings that apply to the whole site, and the title and description of each individual page.

To move a site's SEO configuration to Wix:

1. Collect the SEO configuration from the source site, separating site-wide values, such as the social share image and any verification tags, from per-page values.
1. Call [Get Site SEO Tags](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/get-site-seo-tags) to see the tags the Wix site already has.
1. Build the site-wide tag array by combining the tags to keep with the values from the source site.
1. Call [Set Site SEO Tags](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/set-site-seo-tags) with that array and `tags` in the `fieldMask`.
1. Move the per-page titles and descriptions with the [Item SEO Tags API](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/introduction), which writes the tags of an individual page or item.

Verification tags a Wix user added through the site's SEO settings in the dashboard are returned in `embedTags` and can't be set through this API. Check `embedTags` before adding a verification tag, so you don't duplicate one the site already carries.

Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

One tag in the page's <head>.

Not deprecated, and with no removal date, deliberately: stored data is
never migrated, so this shape stays valid input forever. `seo-renderer`
normalizes both shapes on READ.

Legacy. Was the tag's inner content, doubling as the JSON-LD payload
for script tags. Typed replacement: `SeoSchemaV2.TitleTag.text` and
`StructuredDataTag.json_ld`.
No length limit, for the same reason as `type` above.

children

Whether the tag is a [custom tag](https://support.wix.com/en/article/adding-additional-meta-tags-to-your-sites-pages) —
i.e. an entry from the site's Advanced/Custom Tags list.

Setting this to `true` on a write restricts which `type` values are
accepted — the same restriction the Advanced/Custom Tags UI enforces.
`title` and `script` tags (including JSON-LD structured data) must be sent
with `custom` omitted or `false`; sending them with `custom: true` is
rejected with `TAG_TYPE_NOT_ALLOWED`.

Note this is a separate restriction from Site SEO Tags' own type
restriction on `SiteSeoTags.tags`: even with `custom` unset, Site SEO Tags
rejects `script` (e.g. for site-wide structured data) unconditionally.
There is currently no way to set site-wide, every-page structured data
through any of these APIs — write a per-page `script` tag through the Item
SEO Tags API instead.

This flag is scoped to that feature only. It is NOT an indicator of whether a standard tag
(`title`, `description`, Open Graph, etc.) reflects a manually configured value versus a computed
default/pattern — standard tags always resolve with `custom: false`, even when their content comes
from a page's manually saved SEO title/description override. Don't use this field to verify whether
a live page reflects a manual per-page SEO edit.

Limitation: when `ResolveStaticPageSeoTags` is called without `seoData`, the per-page SEO data is read
only from the Vibe/Wix-managed-headless override store. That store holds nothing for classic Wix Editor
or Wix Studio pages, so even genuine Advanced/Custom Tags saved on those pages are missing from the
response entirely — there, `false` means this API could not tell, not that no custom tag exists.
Pass `seoData` explicitly to resolve against a known set of tags.

`SeoSchemaV2.Tag` expresses this as `written_by = USER_CUSTOM`.

custom

Whether the tag is excluded from the rendered <head>.

A disabled tag is still stored, so the user can re-enable it and so a
pattern-provided tag stays suppressed on this page. Default false.

disabled

Legacy. Was an untyped bag of HTML attributes.
Typed replacement: `SeoSchemaV2.TitleTag` / `MetaTag` / `LinkTag`.

props

Legacy. Was a free-form string: "title" | "meta" | "script" | "link".
The typed replacement is the `kind` oneof on `SeoSchemaV2.Tag`, which makes
the invalid combinations unrepresentable rather than merely discouraged.

Which of these an API actually accepts depends on where the tag is being
set: this list is not a blanket guarantee across every API that reuses
this message. Site SEO Tags in particular accepts only `meta` (see
`SiteSeoTags.tags`) and rejects `title`/`script`/`link` with a validation
error even though they appear here — check the field description of the
specific `tags`-typed field you are writing to.

Limitation: `title` and `script` (e.g. a `script` tag with `props.type`
"application/ld+json" carrying structured data) are supported only when
`custom` is unset or `false`. Setting `custom: true` on a `title` or
`script` tag is rejected with `TAG_TYPE_NOT_ALLOWED`, because
`custom: true` routes the write through the site's Advanced/Custom Tags
list. To write structured data, omit `custom` (or set it to `false`).

No length limit: this field holds data written years ago by writers we
are not migrating. A constraint here could reject a record that is
already stored, which is exactly the promise this design makes.

type

paths

FieldMask

values

ListValue

NullValue

value

StringValue

fields

Struct

Value

boolValue

listValue

nullValue

numberValue

stringValue

structValue

kind

GetSiteSeoTagsRequest

GetSiteSeoTagsResponse

What made a change to a site's SEO tags or patterns. Derived from the caller, not from
the request.

Unknown origin. Returned by read methods, because origin isn't stored alongside the
data it describes.

A user, working in the dashboard or editor, or calling the API on their own behalf.

The flow that imports an existing site into Wix.

An AI agent or an automated suggestion flow.

Origin

Fields to update.

Supported properties: `tags`

Over REST, send the mask as a comma-separated string, for example
`"fieldMask": "tags"`. The JavaScript SDK takes an array of strings
instead, for example `fieldMask: ["tags"]`.

fieldMask

Site SEO tags to set. Only `tags` can be changed.

SetSiteSeoTagsRequest

SetSiteSeoTagsResponse

Site-wide SEO tags are the meta tags that apply to every page of a site, such as
site verification tags, the default social share image, and whether search engines
may index the site.

A site has exactly one set of site SEO tags. Tags that belong to a single page, such
as titles and descriptions, are managed with the Item SEO Tags API, and the patterns
that generate them with the SEO Patterns API.

Site verification tags that were added through the site's SEO settings in the
dashboard, which stores them as HTML embeds rather than as site tags.

Returned so that a read reflects every verification tag on the site. These tags are
never included in `tags`. Empty when the site has none, and also when they can't be
retrieved.

embedTags

Language the tags apply to.

Site SEO tags aren't language specific: one set of tags applies to every language
version of a site. Currently always empty.

language

What made the most recent change to the site's tags, for example a user or the site
migration flow. Derived from the caller, not from the request.

`ORIGIN_UNSPECIFIED` when the caller isn't one Wix identifies as a specific origin.
Origin isn't stored with the tags either, so Get Site SEO Tags always returns
`ORIGIN_UNSPECIFIED`.

origin

SiteSeoTags

Retrieves a site's site-wide SEO tags.

Returns the tags you can change in `tags`, and any site verification tags added
through the dashboard in `embedTags`.

Use this read to check the indexing directives reported for the site.
In `siteSeoTags.tags`, an enabled `robots` meta tag with a `noindex` or `none`
directive reports a site-wide block. An omitted upstream boolean can also decode
as false and produce this tag; the response cannot distinguish it from an explicit
setting. Confirm the dashboard setting and live page before recommending a change.
A successful response without a blocking directive
means no site-wide indexing restriction; individual pages may still be restricted.
This does not report Google's indexing state or inspect a live page. A failed
request does not establish the setting. See the [indexing check flow](https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/sample-flows#check-whether-site-wide-indexing-is-enabled).

The site has no verification tags added through the dashboard, so `embedTags` is empty.

Retrieve a site's SEO tags

GetSiteSeoTags

View SEO Settings

Sets a site's site-wide SEO tags.

List the fields to change in `fieldMask`.

Setting `tags` replaces the site's tags in full, so retrieve the current tags with
[Get Site SEO
Tags](https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/get-site-seo-tags)
and send back the complete set you want the site to have. Two consequences are easy
to miss:

- Leaving out the `robots` tag makes the site indexable again, because no `noindex`
directive remains.
- Leaving out `og:image` clears the site's default social share image.

To remove every site tag, send `tags` as an empty list with `tags` in the field mask.
Site verification tags added through the dashboard are stored separately and aren't
affected.

Tags are validated before anything is saved, so a request that contains an invalid
tag changes nothing.

A tag isn't valid at site level. For example, the tag belongs to a single page
rather than the whole site, its value isn't valid for that tag, it uses an
unsupported `robots` directive, or it repeats a verification provider that
supports a single tag.

The `fieldMask` is empty, or names a field that doesn't exist or can't be changed.

The request carries the tags the site already has together with the new `og:image` tag, because the tags sent replace the site's tags in full.

Add a social share image to a site's SEO tags

SetSiteSeoTags

Manage SEO Settings

Site Seo Tags

addressLine1

addressLine2

city

country

formatted

postalCode

subdivision

Address

nanos

seconds

GoogleProtoDuration

latitude

longitude

Location

name

number

StreetAddress

SetSiteSeoTagsOptions

SetSiteSeoTagsRequestSignature

import { siteSeoTags } from "@wix/seo";

async function getSiteSeoTags() {
  const response = await siteSeoTags.getSiteSeoTags();
  return response;
}

/* Promise resolves to:
 * {
 *   "siteSeoTags": {
 *     "tags": [
 *       {
 *         "type": "meta",
 *         "props": { "name": "description", "content": "Handmade ceramics from a small studio in Lisbon." },
 *         "children": "",
 *         "custom": false,
 *         "disabled": false
 *       },
 *       {
 *         "type": "meta",
 *         "props": { "property": "og:image", "content": "https://static.wixstatic.com/media/a1b2c3_9f8e7d6c5b4a3210.jpg" },
 *         "children": "",
 *         "custom": false,
 *         "disabled": false
 *       }
 *     ],
 *     "embedTags": [],
 *     "origin": "ORIGIN_UNSPECIFIED",
 *     "_id": "118f445d-6b84-4268-821d-7d2b9f40ac60"
 *   }
 * }
 */


The site has no verification tags added through the dashboard, so embedTags is empty.

import { createClient } from '@wix/sdk';
import { siteSeoTags } from '@wix/seo';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { siteSeoTags },
  // Include the auth strategy and host as relevant
});


async function getSiteSeoTags() {
  const response = await myWixClient.siteSeoTags.getSiteSeoTags();
};

Self-managed SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

getSiteSeoTags (self-managed)

import { siteSeoTags } from "@wix/seo";

async function setSiteSeoTags() {
  const response = await siteSeoTags.setSiteSeoTags(
    {
      tags: [
        {
          type: "meta",
          props: { name: "description", content: "Handmade ceramics from a small studio in Lisbon." },
        },
        {
          type: "meta",
          props: {
            property: "og:image",
            content: "https://static.wixstatic.com/media/a1b2c3_9f8e7d6c5b4a3210.jpg",
          },
        },
      ],
    },
    { fieldMask: ["tags"] },
  );
  return response;
}

/* Promise resolves to:
 * {
 *   "siteSeoTags": {
 *     "tags": [
 *       {
 *         "type": "meta",
 *         "props": { "name": "description", "content": "Handmade ceramics from a small studio in Lisbon." },
 *         "children": "",
 *         "custom": false,
 *         "disabled": false
 *       },
 *       {
 *         "type": "meta",
 *         "props": { "property": "og:image", "content": "https://static.wixstatic.com/media/a1b2c3_9f8e7d6c5b4a3210.jpg" },
 *         "children": "",
 *         "custom": false,
 *         "disabled": false
 *       }
 *     ],
 *     "embedTags": [],
 *     "origin": "ORIGIN_UNSPECIFIED",
 *     "_id": "118f445d-6b84-4268-821d-7d2b9f40ac60"
 *   }
 * }
 */


The request carries the tags the site already has together with the new og:image tag, because the tags sent replace the site's tags in full.

import { createClient } from '@wix/sdk';
import { siteSeoTags } from '@wix/seo';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { siteSeoTags },
  // Include the auth strategy and host as relevant
});


async function setSiteSeoTags(siteSeoTags,options) {
  const response = await myWixClient.siteSeoTags.setSiteSeoTags(siteSeoTags,options);
};

Get Site Seo Tags