> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # GenerateHeadingStructureSuggestions # Package: seo # Namespace: TagsSuggestionsService # Method link: https://dev.wix.com/docs/api-reference/business-management/seo/tag-suggestions-v1/generate-heading-structure-suggestions.md ## Permission Scopes: View SEO Settings: SCOPE.PROMOTE.VIEW-SEO ## Introduction Suggests corrected heading levels for a page's headings. Pass the page's headings in document order, each with its raw HTML and your own reference IDs. The AI checks the heading hierarchy (one H1, no skipped levels, headings that match their content) and returns a suggested tag per heading that should change, echoing your reference IDs back so you can locate each element. The heading nodes are the request's content, so this method works for any page, including headless projects. This method must be called with a [Wix user identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities.md), for example an app acting on behalf of a signed-in site owner. Calls made with an API key fail, because the page's title is read through the site's accessibility analysis, which runs as the user. --- ## REST API ### Schema ``` Method: generateHeadingStructureSuggestions Description: Suggests corrected heading levels for a page's headings. Pass the page's headings in document order, each with its raw HTML and your own reference GUIDs. The AI checks the heading hierarchy (one H1, no skipped levels, headings that match their content) and returns a suggested tag per heading that should change, echoing your reference GUIDs back so you can locate each element. The heading nodes are the request's content, so this method works for any page, including headless projects. This method must be called with a [Wix user identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities.md), for example an app acting on behalf of a signed-in site owner. Calls made with an API key fail, because the page's title is read through the site's accessibility analysis, which runs as the user. URL: https://www.wixapis.com/seo/suggestions/v1/tag-suggestions/heading-structure Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: headings, pageId, itemType Method parameters: param name: headings | type: array | description: The page's heading elements, in the order they appear on the page. | required: true | validation: maxItems 200 - name: id | type: string | description: Your reference GUID for the heading element. Required, and must be unique within the request together with `uiElementId` and `attributeId` if you send them. | validation: minLength 1, maxLength 1000 - name: attributeId | type: string | description: Additional reference GUID for the heading's text attribute, if you use one. Echoed back unchanged. | validation: maxLength 1000 - name: htmlString | type: string | description: Raw HTML of the heading element, including its tag, for example, `

Our services

`. Elements that aren't headings are ignored for the structure check. Send page content only. Don't include personal data. | validation: minLength 1, maxLength 100000 - name: uiElementId | type: string | description: Additional reference GUID for the heading element, if you use one. Echoed back unchanged. | validation: maxLength 1000 - name: sectionId | type: string | description: Your reference GUID for the page section the heading belongs to. Helps the AI keep one heading hierarchy per section. | validation: maxLength 1000 param name: itemType | type: itemType | description: Type of the page's item, as an SEO item type identifier. For example, `STATIC_PAGE_V2` for a regular site page or `BLOG_POST` for a blog post. Other values are rejected. | required: true | validation: minLength 1, maxLength 200 param name: pageId | type: pageId | description: Your reference GUID for the page the headings belong to. For Wix pages, the page GUID, which lets the page's title be read to give the AI context. | required: true | validation: minLength 1, maxLength 200 Return type: GenerateHeadingStructureSuggestionsResponse - name: suggestions | type: array | description: A suggestion per heading whose level should change. Headings that are already correct aren't returned. | read-only: true | validation: maxItems 200 - name: headingId | type: string | description: Your reference GUID for the heading element, echoed from the request. | read-only: true | validation: maxLength 1000 - name: uiElementId | type: string | description: Your `uiElementId` reference, echoed from the request. | read-only: true | validation: maxLength 1000 - name: attributeId | type: string | description: Your `attributeId` reference, echoed from the request. | read-only: true | validation: maxLength 1000 - name: currentTag | type: string | description: The heading's current tag. For example, `H2`. | read-only: true | validation: maxLength 10 - name: proposedTag | type: string | description: The suggested tag. For example, `H3`, or `P` for text that shouldn't be a heading. | read-only: true | validation: maxLength 10 Possible Errors: HTTP Code: 429 | Status Code: RESOURCE_EXHAUSTED | Application Code: QUOTA_LIMIT_REACHED | Description: The caller's generation quota is exhausted. Reserved for future metering and not currently returned. HTTP Code: 500 | Status Code: INTERNAL | Application Code: GENERATION_FAILED | Description: The AI generation pipeline failed. Retry the call. ``` ### Examples ### Suggest corrected heading levels for a page The page has an H1 followed by an H3, an H4, and a second H1. The response proposes the level each heading should have. ```curl curl -X POST \ 'https://www.wixapis.com/seo/suggestions/v1/tag-suggestions/heading-structure' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "pageId": "c1dmp", "itemType": "STATIC_PAGE_V2", "headings": [ { "id": "hero-title", "htmlString": "

Portland Pottery Studio

", "sectionId": "hero" }, { "id": "services-title", "htmlString": "

Our services

", "sectionId": "services" }, { "id": "services-classes", "htmlString": "

Wheel-throwing classes

", "sectionId": "services" }, { "id": "contact-title", "htmlString": "

Contact us

", "sectionId": "contact" } ] }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.seo.tagSuggestions.generateHeadingStructureSuggestions(headings, options) Description: Suggests corrected heading levels for a page's headings. Pass the page's headings in document order, each with its raw HTML and your own reference GUIDs. The AI checks the heading hierarchy (one H1, no skipped levels, headings that match their content) and returns a suggested tag per heading that should change, echoing your reference GUIDs back so you can locate each element. The heading nodes are the request's content, so this method works for any page, including headless projects. This method must be called with a [Wix user identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities.md), for example an app acting on behalf of a signed-in site owner. Calls made with an API key fail, because the page's title is read through the site's accessibility analysis, which runs as the user. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: headings, options.pageId, options.itemType, options Method parameters: param name: headings | type: array | description: The page's heading elements, in the order they appear on the page. | required: true | validation: maxItems 200 - name: _id | type: string | description: Your reference GUID for the heading element. Required, and must be unique within the request together with `uiElementId` and `attributeId` if you send them. | validation: minLength 1, maxLength 1000 - name: attributeId | type: string | description: Additional reference GUID for the heading's text attribute, if you use one. Echoed back unchanged. | validation: maxLength 1000 - name: htmlString | type: string | description: Raw HTML of the heading element, including its tag, for example, `

Our services

`. Elements that aren't headings are ignored for the structure check. Send page content only. Don't include personal data. | validation: minLength 1, maxLength 100000 - name: uiElementId | type: string | description: Additional reference GUID for the heading element, if you use one. Echoed back unchanged. | validation: maxLength 1000 - name: sectionId | type: string | description: Your reference GUID for the page section the heading belongs to. Helps the AI keep one heading hierarchy per section. | validation: maxLength 1000 param name: options | type: GenerateHeadingStructureSuggestionsOptions none | required: true - name: pageId | type: string | description: Your reference GUID for the page the headings belong to. For Wix pages, the page GUID, which lets the page's title be read to give the AI context. | required: true | validation: minLength 1, maxLength 200 - name: itemType | type: string | description: Type of the page's item, as an SEO item type identifier. For example, `STATIC_PAGE_V2` for a regular site page or `BLOG_POST` for a blog post. Other values are rejected. | required: true | validation: minLength 1, maxLength 200 Return type: PROMISE - name: suggestions | type: array | description: A suggestion per heading whose level should change. Headings that are already correct aren't returned. | read-only: true | validation: maxItems 200 - name: headingId | type: string | description: Your reference GUID for the heading element, echoed from the request. | read-only: true | validation: maxLength 1000 - name: uiElementId | type: string | description: Your `uiElementId` reference, echoed from the request. | read-only: true | validation: maxLength 1000 - name: attributeId | type: string | description: Your `attributeId` reference, echoed from the request. | read-only: true | validation: maxLength 1000 - name: currentTag | type: string | description: The heading's current tag. For example, `H2`. | read-only: true | validation: maxLength 10 - name: proposedTag | type: string | description: The suggested tag. For example, `H3`, or `P` for text that shouldn't be a heading. | read-only: true | validation: maxLength 10 Possible Errors: HTTP Code: 429 | Status Code: RESOURCE_EXHAUSTED | Application Code: QUOTA_LIMIT_REACHED | Description: The caller's generation quota is exhausted. Reserved for future metering and not currently returned. HTTP Code: 500 | Status Code: INTERNAL | Application Code: GENERATION_FAILED | Description: The AI generation pipeline failed. Retry the call. ``` ### Examples ### Suggest corrected heading levels for a page The page has an H1 followed by an H3, an H4, and a second H1. The response proposes the level each heading should have. ```javascript import { tagSuggestions } from "@wix/seo"; async function generateHeadingStructureSuggestions() { const response = await tagSuggestions.generateHeadingStructureSuggestions( [ { _id: "hero-title", htmlString: "

Portland Pottery Studio

", sectionId: "hero", }, { _id: "services-title", htmlString: "

Our services

", sectionId: "services", }, { _id: "services-classes", htmlString: "

Wheel-throwing classes

", sectionId: "services", }, { _id: "contact-title", htmlString: "

Contact us

", sectionId: "contact", }, ], { pageId: "c1dmp", itemType: "STATIC_PAGE_V2", }, ); } /* Promise resolves to: * { * "suggestions": [ * { * "headingId": "services-title", * "currentTag": "H3", * "proposedTag": "H2" * }, * { * "headingId": "services-classes", * "currentTag": "H4", * "proposedTag": "H3" * }, * { * "headingId": "contact-title", * "currentTag": "H1", * "proposedTag": "H2" * } * ] * } */ ``` ### generateHeadingStructureSuggestions (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { tagSuggestions } from '@wix/seo'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { tagSuggestions }, // Include the auth strategy and host as relevant }); async function generateHeadingStructureSuggestions(headings,options) { const response = await myWixClient.tagSuggestions.generateHeadingStructureSuggestions(headings,options); }; ``` ---