API reference meta data - WEBSALE Dokumentation

The seo/texts/ endpoint provides an interface for managing SEO meta data for different areas of the shop (e.g. pages, categories, products). The API lets you maintain meta titles and meta descriptions manually or reset them to the automatically generated default values when needed. Meta data is either set directly or generated based on stored schemas.

Supported methods

List of all supported methods.

Command/Info	Endpoints	GET	POST	PUT	DELETE
Meta data of shop pages	seo/texts/
Reset to default settings	seo/texts/…/reset
Refresh all SEO texts	seo/texts/update

Data fields (meta data resource)

Meta data of category and product pages are stored in the user-defined fields metaTitle and metaDescription. To work with them, the categories/ and products/ endpoints are used. Meta data of the home page is located in subshop-specific configurations and cannot be queried via API. For meta data of the other shop pages there is a table in the database.

Data fields

Name	Type	Meaning
id	Integer	Unique ID of the record
resourceId	String	Unique name of the page including path.
metaTitle	String	Contains the meta title of the page.
metaTitleSetManually	Boolean	Indicates whether the meta title was set manually and should not change after the schema is updated.
metaDescription	String	Contains the meta description of the page.
metaDescriptionSetManually	Boolean	Indicates whether the meta description was set manually and should not change after the schema is updated.
createdAt	String	Time when the meta data was created (ISO 8601 format, UTC).
updatedAt	String	Time of the last update of the meta data (ISO 8601 format, UTC).

Example of a record

{
    "createdAt": "2025-01-22 19:49:29",
    "id": 7,
    "metaDescription": "some text",
    "metaDescriptionSetManually": true,
    "metaTitle": "some generated text",
    "metaTitleSetManually": false,
    "resourceId": "newPage2",
    "updatedAt": "2025-01-22 19:49:34"
}

Methods for meta data of shop pages (views)

This section contains all endpoints for managing meta data for shop pages, which are internally referred to as views. You can update or reset meta data such as title and description, fetch data of existing pages, register new pages and delete individual entries. The views are uniquely identified by their resourceId. Permissions for SEO data are required.

GET seo/texts/views

This method returns a paginated list of meta data (e.g. title and description) of all page resources existing in the shop that can be maintained for SEO purposes. Using the filter and sort parameters, you can load only certain entries — for example, only pages with manually set meta titles or descriptions. The number of entries per page can be set with the size parameter in the range from 1 to 300. To use it, read permissions for SEO data are required.

Example

https://www.<your-shop>.de/admin/api/v1/seo/texts/views

Response

{
    "endReached": true,
    "items": [
        {
            "createdAt": "2025-01-09 11:07:55",
            "id": 5,
            "metaDescription": "",
            "metaDescriptionSetManually": true,
            "metaTitle": "My page",
            "metaTitleSetManually": true,
            "resourceId": "newPage",
            "updatedAt": "2025-03-06 16:10:42"
        },
        ...
    ],
    "nextPageToken": "NA",
    "totalCount": 5
}

Filter fields

createdAt, updatedAt, metaTitleSetManually, metaDescriptionSetManually

Sort fields

createdAt, updatedAt, resourceId, metaTitle, metaDescription

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read SEO data.
400 Bad Request	”invalidValue"	"stage” is invalid. `size` ∉ [1;300] `pageToken` is not a number or is less than 0. `sort` direction is neither “asc” nor “desc”.
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:“.
503 Service Unavailable	”internalError”	Reading data failed.

POST seo/texts/views

This method can be used to register a new shop page for SEO management. When creating, metaTitle and metaDescription are stored empty initially. A unique page name (viewName) must be provided, which will serve as resourceId. The name must not already exist. For this action, create permissions for SEO data are required. Note: If a new shop page is not registered manually, meta data is generated for it automatically based on the schema from the configuration when it is accessed for the first time.

Example

https://www.<your-shop>.de/admin/api/v1/seo/texts/views

Request body

{
    "viewName": "Über uns"
}

Response

{
    "createdAt": "2025-01-22 19:49:29",
    "id": 7,
    "metaDescription": "",
    "metaDescriptionSetManually": false,
    "metaTitle": "",
    "metaTitleSetManually": false,
    "resourceId": "Über uns",
    "updatedAt": "2025-01-22 19:49:29"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create SEO data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidValue"	"stage” is invalid.
409 Conflict	”existsAlready”	The name already exists in the table.
503 Service Unavailable	”internalError”	The page could not be registered.

PUT seo/texts/views/{viewId}

This method can be used to selectively update the SEO meta data (title and description) of a specific shop page. Only metaTitle and/or metaDescription may be changed — accompanying technical fields such as metaTitleSetManually, metaDescriptionSetManually and updatedAt are set automatically. The viewId must be specified in the URL. This is the numeric id of the record (not the resourceId). To update, the appropriate write permissions for SEO data must be available.

Example

https://www.<your-shop>.de/admin/api/v1/seo/texts/views/5

Request body

{
    "metaDescription": "Informieren Sie sich hier über die Allgemeinen Geschäftsbedingungen (AGB)"
}

Response

{
    "createdAt": "2025-01-09 11:07:55",
    "id": 5,
    "metaDescription": "Informieren Sie sich hier über die Allgemeinen Geschäftsbedingungen (AGB)",
    "metaDescriptionSetManually": true,
    "metaTitle": "My page",
    "metaTitleSetManually": true,
    "resourceId": "agb",
    "updatedAt": "2025-03-06 16:10:42"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write SEO data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidValue"	"stage” is invalid. `viewId` is not a valid number.
400 Bad Request	”missing”	`viewId` is missing.
404 Not Found		There is no page with the given `id`.
503 Service Unavailable	”internalError”	Data update failed.

PUT seo/texts/views/reset

This endpoint resets the manually set meta data of selected pages and replaces them with automatically generated values according to the defined schema. The fields metaTitleSetManually and metaDescriptionSetManually are set to false. Write permissions for SEO data are required.

Example

https://www.<your-shop>.de/admin/api/v1/seo/texts/views/reset

Request body

{
    "items": [
        "newPage",
        "newPage2"
    ]
}

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write SEO data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidValue"	"stage” is invalid.

DELETE seo/texts/views/{viewId}

This endpoint can be used to selectively delete the meta data (title and description) of a registered page. The page is identified by its numeric id. To execute, delete permissions for SEO data are required.

Example

https://www.<your-shop>.de/admin/api/v1/seo/texts/views/5

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete SEO data.
400 Bad Request	”invalidValue"	"stage” is invalid. `viewId` is not a valid number.
400 Bad Request	”missing”	`viewId` is missing.
404 Not Found		The page was not found.

Methods for meta data of categories

This section covers the processing of SEO meta data for categories. The API only allows resetting manually maintained meta titles and meta descriptions. Existing content is removed and replaced with values generated based on a schema.

PUT seo/texts/categories/reset

Resets the meta data of the provided categories. Manually set fields metaTitle and metaDescription are replaced by automatically generated content. The fields metaTitleSetManually and metaDescriptionSetManually are set to false. Write permissions for SEO data are required.

Example

https://www.<your-shop>.de/admin/api/v1/seo/texts/categories/reset

Request body

{
    "items": [
        "cat1",
        "cat2"
    ]
}

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write SEO data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidValue"	"stage” is invalid.

Methods for meta data of products

Only a reset option is available for products. The API does not offer a way to update individual SEO fields directly. Instead, manual meta data is completely replaced with automatically generated data.

PUT seo/texts/products/reset

This endpoint deletes the manually entered meta data of products and replaces them with generated content. The fields metaTitleSetManually and metaDescriptionSetManually are set to false. Write permissions for SEO data are required.

Example

https://www.<your-shop>.de/admin/api/v1/seo/texts/products/reset

Request body

{
    "items": [
        "prod1",
        "prod2"
    ]
}

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write SEO data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidValue"	"stage” is invalid.

Refreshing all SEO texts

This section describes the endpoint for manually triggering a refresh of all SEO texts according to the configured schemas.

PUT seo/texts/update

This endpoint triggers a refresh of all SEO texts in the shop. Meta titles and meta descriptions that were not set manually are regenerated based on the configured schema. Write permissions for SEO data are required.

Example

https://www.<your-shop>.de/admin/api/v1/seo/texts/update

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write SEO data.
400 Bad Request	”invalidValue"	"stage” is invalid.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

​Supported methods

​Data fields (meta data resource)

​Data fields

​Example of a record

​Methods for meta data of shop pages (views)

​GET seo/texts/views

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​POST seo/texts/views

​Example

​Request body

​Response

​Error codes

​PUT seo/texts/views/{viewId}

​Example

​Request body

​Response

​Error codes

​PUT seo/texts/views/reset

​Example

​Request body

​Response

​Error codes

​DELETE seo/texts/views/{viewId}

​Example

​Response

​Error codes

​Methods for meta data of categories

​PUT seo/texts/categories/reset

​Example

​Request body

​Response

​Error codes

​Methods for meta data of products

​PUT seo/texts/products/reset

​Example

​Request body

​Response

​Error codes

​Refreshing all SEO texts

​PUT seo/texts/update

​Example

​Response

​Error codes

​Support

Supported methods

Data fields (meta data resource)

Data fields

Example of a record

Methods for meta data of shop pages (views)

GET seo/texts/views

Example

Response

Filter fields

Sort fields

Error codes

POST seo/texts/views

Example

Request body

Response

Error codes

PUT seo/texts/views/{viewId}

Example

Request body

Response

Error codes

PUT seo/texts/views/reset

Example

Request body

Response

Error codes

DELETE seo/texts/views/{viewId}

Example

Response

Error codes

Methods for meta data of categories

PUT seo/texts/categories/reset

Example

Request body

Response

Error codes

Methods for meta data of products

PUT seo/texts/products/reset

Example

Request body

Response

Error codes

Refreshing all SEO texts

PUT seo/texts/update

Example

Response

Error codes

Support