API reference SEO URLs - WEBSALE Dokumentation

The seo/urls/ endpoint provides an interface that allows you to hide the technical names of shop pages and use clearer labels instead. They can be set manually or generated according to a schema.

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, e.g. by creation date or product ID. The size parameter controls the number of entries per page and must be in the range 1–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 retrieves a list of SEO URLs for general shop pages (e.g. login, registration). The results can be filtered and sorted using optional parameters. The size parameter sets the maximum number of results per page and must be in the range from 1 to 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

URLs are regenerated. The optional deleteOld parameter determines whether all URLs that are currently not used but still valid are deleted. Whether a URL is used in the shop and not 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 starts the (re)generation of an SEO URL. The old value is not deleted. 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 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.
400 Bad Request	”invalidFormat”	`viewControllerId`, `resourceIdentifier` or `optimalPathEsc` is not a string.
400 Bad Request	”unknownDataField”	An unknown field was provided.

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