API reference SEO URLs - WEBSALE Dokumentation

The seo/urls/ endpoint provides an interface that allows you to replace the technical names of shop pages with clearer labels. You can either set these labels manually or have them generated according to a specific schema. The following sections first describe the data fields of an SEO URL and then the individual methods.

Supported methods

List of all supported methods.

Command/Info	Endpoints	GET	POST	PUT	DELETE
SEO URLs of shop pages	seo/urls/

Data fields

Name	Type	Usage
path	String	Path used to output the URL
main	Boolean	Indicates whether the URL is used in the current version of the shop.
manual	Boolean	Indicates whether the URL was set manually.
name (for categories and products)	String	The name of the category or product
resourceIdentifier	String	Page name or identifier for a category/product
updatedAt	String	Time of the last update (ISO 8601 format, UTC)
createdAt	String	Time of creation (ISO 8601 format, UTC)

Example (product)

{
    "createdAt": "2024-06-13T12:12:53.000Z",
    "main": 1,
    "manual": 0,
    "path": "/Bekleidung/Damen_NOOS_High-Waist_Curvy_Skinny_Jeans",
    "resourceIdentifier": "100-69659",
    "updatedAt": "2024-06-13T12:12:53.000Z"
}

Example (category)

{
    "createdAt": "2025-04-28T11:20:45.000Z",
    "main": 1,
    "manual": 1,
    "name": "Elektronik & Computer",
    "path": "/Elektronik-Computer",
    "resourceIdentifier": "101-64607",
    "updatedAt": "2025-04-28T11:20:45.000Z"
}

Example (shop page)

{
    "createdAt": "2025-05-06T08:16:05.000Z",
    "main": 1,
    "manual": 1,
    "path": "/checkout",
    "resourceIdentifier": "checkout.htm",
    "updatedAt": "2025-05-06T08:16:05.000Z"
}

Using the methods

This section describes the available endpoints for managing SEO URLs. They let you query, generate, validate, update and delete SEO URLs for categories, products and templates in the shop system. Using these methods requires the corresponding permissions to read or edit SEO data.

GET seo/urls/generate/status

This endpoint is used to check the current status of SEO URL generation. It indicates whether a generation process is currently running ("running": true) or has already been completed ("running": false). This is particularly helpful when, after starting a generation process, you have to wait for its completion before proceeding. To use this endpoint, the corresponding read permissions for SEO data are required.

Example

https://www.<your-shop>.de/admin/api/v1/seo/urls/generate/status

Response

{
    "running": 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 read SEO data.

GET seo/urls/categories

The GET seo/urls/categories endpoint returns a list of SEO URLs for categories. The list can be limited using sort and filter parameters. The optional size parameter determines the number of returned results and must be in the range from 1 to 300. To use this endpoint, the corresponding permissions to read SEO data are required.

Example

The example fetches all SEO URLs of categories that are currently used in the shop and are not just valid (main = 1) and sorts the results ascending by the resourceIdentifier field.

https://www.<your-shop>.de/admin/api/v1/seo/urls/categories?sort=resourceIdentifier:asc&filter_eq[main]=1

Response

{
    "endReached": false,
    "items": [
        {
            "createdAt": "2024-11-15T10:20:10Z",
            "index": 0,
            "name": "Neue Kategorie",
            "path": "/Neue_Kategorie-154",
            "resourceIdentifier": "1000-85809",
            "status": "test",
            "updatedAt": "2024-11-15T10:20:10Z"
        },
        ...
    ],
    "nextPageToken": "MTAw",
    "totalCount": 262
}

Filter fields

createdAt, updatedAt, resourceIdentifier, path, manual, main

Sort fields

createdAt, updatedAt, resourceIdentifier, path, main

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”	`size` ∉ [1;300] `pageToken` is invalid.
400 Bad Request	”invalidCharacters”
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:“.
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.

GET seo/urls/products

This endpoint returns a list of all SEO URLs for products. Using optional parameters, the results can be filtered and sorted, for example by creation date or product ID. The size parameter controls the number of entries per page. It must contain a value between 1 and 300. For access, the corresponding read permissions for SEO data are required.

Example

https://www.<your-shop>.de/admin/api/v1/seo/urls/products?sort=resourceIdentifier:asc

Response

{
    "endReached": true,
    "items": [
        {
            "createdAt": "2024-11-15T10:20:10Z",
            "index": 1,
            "name": "Something",
            "path": "/MyCategory/Something",
            "resourceIdentifier": "100-41232",
            "status": "never",
            "updatedAt": "2024-11-15T10:20:10Z"
        },
        ...
    ],
    "nextPageToken": "Mzg",
    "totalCount": 39
}

Filter fields

createdAt, updatedAt, resourceIdentifier, path, manual, main

Sort fields

createdAt, updatedAt, resourceIdentifier, path, main

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”	`size` ∉ [1;300] `pageToken` is invalid.
400 Bad Request	”invalidCharacters”
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:“.
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.

GET seo/urls/templates

This endpoint can be used to retrieve a list of SEO URLs for general shop pages (for example login or registration). The results can be filtered and sorted using optional parameters. The size parameter sets the maximum number of results per page. It must contain a value between 1 and 300. For access, the corresponding read permissions for SEO data are required.

Example

https://www.<your-shop>.de/admin/api/v1/seo/urls/templates?sort=resourceIdentifier:desc

Response

{
    "endReached": true,
    "items": [
        {
            "createdAt": "2025-01-25T08:30:23Z",
            "index": 0,
            "path": "",
            "resourceIdentifier": "login.htm",
            "updatedAt": "2025-01-25T08:30:23Z"
        }
    ],
    "nextPageToken": "MA",
    "totalCount": 1
}

Filter fields

createdAt, updatedAt, resourceIdentifier, path, manual, main

Sort fields

createdAt, updatedAt, resourceIdentifier, path, main

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”	`size` ∉ [1;300] `pageToken` is invalid.
400 Bad Request	”invalidCharacters”
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:“.
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.

POST seo/urls/check

This endpoint checks whether a specific SEO path (seoPath) is already used in the system and returns additional information about the associated resource. This can be used, for example, to avoid potential collisions before saving new URLs. Use requires write permissions for SEO data.

Example

https://www.<your-shop>.de/admin/api/v1/seo/urls/check

Request body

{
    "seoPath": "/neue_kategorie-176/"
}

Response

{
    "available": false,
    "main": true,
    "resourceIdentifier": "1001-26578",
    "viewController": "Category"
}

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	”missing”	`seoPath` was not provided.
400 Bad Request	”invalidFormat”	`seoPath` is not a string.
400 Bad Request	”unknownDataField”	An unknown field was provided.

POST seo/urls/generate

This endpoint starts the regeneration of all SEO URLs for products and categories in the background. The response only confirms the start. GET seo/urls/generate/status shows whether the generation is still running. The optional deleteOld parameter determines whether all URLs that are currently not used but still valid should be deleted. Whether a URL is used in the shop or is just valid is determined by the main field.

Example

https://www.<your-shop>.de/admin/api/v1/seo/urls/generate

Request body

{
    "deleteOld": false
}

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 create SEO data.
400 Bad Request		Request body could not be loaded.

POST seo/urls/reset

This endpoint can be used to reset the SEO URL of a single page. Manually maintained URLs of this page are discarded and the URL is then recreated according to the configured schema. The new main URL can be found in the mainPath field of the response. Using the endpoint requires write permissions for SEO data.

Example

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

Request body

{
    "viewControllerId": "Product",
    "resourceIdentifier": "139-55414"
}

Response

{
    "success": true,
    "mainPath": "myURL"
}

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	”missing”	`viewControllerId` or `resourceIdentifier` were not provided.
400 Bad Request	”invalidFormat”	`viewControllerId` or `resourceIdentifier` is not a string.
400 Bad Request	”unknownDataField”	An unknown field was provided.

PUT seo/urls

This endpoint can be used to create a new SEO URL or update an existing one. You must specify the controller (viewControllerId) and object (resourceIdentifier) the URL is assigned to. The URL is defined by optimalPathEsc. The shop checks manually maintained paths. Spaces, control characters and the characters ? and # are not allowed, nor are the path segments . and ... If optimalPathEsc contains such characters or segments, the shop rejects the request and does not save the path. If the leading slash is missing from optimalPathEsc, the shop adds it automatically. The URL that is set becomes the main URL (main) of the page. The previous URLs of the page continue to lead to it, so existing links remain valid. The endpoint requires write permissions for SEO data.

Example

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

Request body

{
    "viewControllerId": "Product",
    "resourceIdentifier": "100-41232",
    "optimalPathEsc": "/NewCategory/Something"
}

Response

{
    "success": true,
    "mainPath": "/NewCategory/Something"
}

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	”missing”	`viewControllerId`, `resourceIdentifier` or `optimalPathEsc` were not provided. `optimalPathEsc` is empty or consists only of `/`.
400 Bad Request	”invalidFormat”	`viewControllerId`, `resourceIdentifier` or `optimalPathEsc` is not a string.
400 Bad Request	”unknownDataField”	An unknown field was provided.
400 Bad Request	”invalidFormat”	`optimalPathEsc` contains spaces, control characters, `?` or `#`, or a path segment `.` or `..`.

DELETE seo/urls

This endpoint can be used to remove an existing SEO URL. After deletion, the URL is no longer reachable, and no automatic redirect is performed anymore. The endpoint requires delete permissions for SEO data.

Example

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

Request body

{
    "seoPath": "/Neue_Kategorie/Neues_Produkt-7"
}

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		Request body could not be loaded.
400 Bad Request	”missing”	`seoPath` was not provided.
400 Bad Request	”invalidFormat”	`seoPath` is not a string.
400 Bad Request	”unknownDataField”	An unknown field was provided.
404 Not found		The URL was not found.

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

​Example (product)

​Example (category)

​Example (shop page)

​Using the methods

​GET seo/urls/generate/status

​Example

​Response

​Error codes

​GET seo/urls/categories

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET seo/urls/products

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET seo/urls/templates

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​POST seo/urls/check

​Example

​Request body

​Response

​Error codes

​POST seo/urls/generate

​Example

​Request body

​Response

​Error codes

​POST seo/urls/reset

​Example

​Request body

​Response

​Error codes

​PUT seo/urls

​Example

​Request body

​Response

​Error codes

​DELETE seo/urls

​Example

​Request body

​Response

​Error codes

​Support

Supported methods

Data fields

Example (product)

Example (category)

Example (shop page)

Using the methods

GET seo/urls/generate/status

Example

Response

Error codes

GET seo/urls/categories

Example

Response

Filter fields

Sort fields

Error codes

GET seo/urls/products

Example

Response

Filter fields

Sort fields

Error codes

GET seo/urls/templates

Example

Response

Filter fields

Sort fields

Error codes

POST seo/urls/check

Example

Request body

Response

Error codes

POST seo/urls/generate

Example

Request body

Response

Error codes

POST seo/urls/reset

Example

Request body

Response

Error codes

PUT seo/urls

Example

Request body

Response

Error codes

DELETE seo/urls

Example

Request body

Response

Error codes

Support