> ## Documentation Index > Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt > Use this file to discover all available pages before exploring further. # API basics > Foundations of the WEBSALE Admin Interface REST API: base URL, user accounts, permissions, services, HTTP methods, and query parameter handling. The REST API gives you the option of interacting with the shop system in an automated way — for example to manage product data, read orders, or connect your own integrations. This document describes the basic prerequisites and technical concepts for working with the API. *** ## Base URL All REST API endpoints are available under the following path: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/ ``` This URL is the base for all requests, e.g. ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} GET https://.de/admin/api/v1/products ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} POST https://.de/admin/api/v1/login ``` ## Access & permissions Access to the REST API requires a user account that is managed in the admin interface of your shop. The admin interface is divided into so-called services (e.g. Products, Categories, Sitemaps, SEO URLs, Data Feeds, Statistics, etc.). Permissions can be assigned in the admin area for each service — for example Read, Edit, Create, Delete, or Publish. These permissions also apply to the REST API and determine which endpoints you can access and which HTTP methods (GET, POST, PUT, DELETE) you may use. A user with only read permissions for the "Products" service, for example, can only retrieve products via API (GET) but cannot edit them (PUT/POST/DELETE). You can view your assigned permissions in the admin interface under the following path: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/profile ``` Permissions are assigned via the "Users" service: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/administration/users ``` Some endpoints work with subshop-specific data. In these cases, the relevant subshop must be specified explicitly via the URL parameter `subshopId`. This applies, among other things, to methods for products, categories, SEO data, and similar context-dependent content. ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/categories?subshopId=deutsch ``` If the parameter is omitted, the request may fail or return unexpected results. If access to specific REST endpoints is denied, you may be missing the required permissions. In this case, contact your responsible shop administrator. *** ## Authentication A login is required to access protected REST API endpoints. Authentication is performed either via username/password or via API key. Successfully authenticated requests receive an access token that can be used to call additional endpoints. A refresh token is also provided. The login is performed via the following endpoint: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} POST https://.de/admin/api/v1/login ``` The access token received must be sent along with all subsequent API calls in the HTTP header. The header must contain the field `X-Authorization`. The value consists of the word `Bearer` followed by the token: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} "X-Authorization": "Bearer " ``` For details on authentication (request variants, token usage, error codes, etc.), see the separate documentation: [API reference authentication](/en/schnittstellen/admin-interface-api/api-referenz-authentifizierung) *** ## Filtering, sorting & pagination Many REST endpoints return lists of data — such as products, orders, or categories. To work efficiently with this data, the API provides various parameters with which results can be narrowed down, sorted, and retrieved page by page. These mechanisms are particularly important for large datasets in order to enable performant and targeted queries. An API call can contain various parameters. A typical GET request might look like this: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/?size=100&sort=field1:asc&filter_eq[field2]=value&pageToken=MTAw ``` The API response has a standardized structure and, in addition to the requested data records, contains further meta information such as the `nextPageToken`, the total counter (`totalCount`), and the `endReached` flag, which indicates whether further pages are available: ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "endReached": true, "items": [...], "nextPageToken": "MTAx", "totalCount": 123 } ``` ### Supported parameters The following URL parameters are supported to control result lists. The notation is case-sensitive. | **Parameter** | **Description** | | ------------- | ------------------------------------------------------------------------------------------------------------------- | | `size` | Number of returned entries per page (1 to **maximum 300**) | | `pageToken` | Optional pagination marker for retrieving the next page | | `sort` | Result sorting by one or more fields | | `filter_...` | Filter conditions to restrict the results | | `subshopId` | Optional parameter to restrict to a specific subshop. Required for some endpoints (e.g. Products, Categories, SEO). | | `textSearch` | Optional parameter for full-text search. | ### Count & pagination The number of data records returned per API request can be controlled via the `size` parameter. The value must be an integer between 1 and 300. If no `size` parameter is passed, the API uses a default value of 100 entries per page. If the requested data set is larger than the defined `size` value (or larger than the default value), the API returns a `nextPageToken` in the response, with which additional pages can be loaded. The pagination mechanism allows large amounts of data to be retrieved step by step. #### Example Example of a manually set page size. ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/?size=50 ``` #### Error codes | **Error code** | **Type** | **Description** | | -------------- | ------------------ | ------------------------------------- | | 400 | `InvalidCharacter` | Invalid characters in parameter value | | 400 | `InvalidValue` | Value less than 1 or greater than 300 | The `pageToken` parameter enables access to subsequent pages of result lists. The value is automatically returned by the API as `nextPageToken` and must be passed in base64-url encoded form. If the encoding is faulty or invalid, an error message is returned. #### Example ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/?size=100&pageToken=MTAw ``` #### Error codes | **Error code** | **Type** | **Description** | | -------------- | -------- | -------------------------------------------------- | | 400 | | Token cannot be decoded, or is negative or invalid | ### Special case: products Loading products via pageToken can be slow if there are more than 10,000 products in the shop. In addition to the pageToken, a `searchAfterToken` is also returned for products. Instead of `pageToken`, `searchAfterToken` can be specified in the URL to load products efficiently even with many results. #### Example ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/?size=300&searchAfterToken=WzAuMCwiMTAwLTQxMjMyLTk3NDFfZGV1dHNjaF8zIl0 ``` ### Sorting Results are sorted via the `sort` parameter. It expects a field name and a sort direction (`asc` for ascending, `desc` for descending), separated by a colon, as the value. To combine multiple sort criteria, multiple sort parameters must be passed. Each parameter stands for a single criterion. A comma-separated list within a parameter is not supported. If no sort parameter is specified, sorting is by internal ID by default. #### Syntax ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} sort=:asc|desc ``` #### Sorting by price ascending ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/?sort=price:asc ``` Another example of sorting by name (ascending) and then by price (descending): ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/?sort=name:asc&sort=price:desc ``` #### Error codes | **Error code** | **Type** | **Description** | | -------------- | -------------- | -------------------------------------------- | | 400 | `SyntaxError` | Missing or multiple colons. | | 400 | `InvalidValue` | Invalid sort direction (not `asc` or `desc`) | | 400 | `UnknownField` | The specified sort field is unknown | ### Filters Filters allow targeted restriction of result lists. Each filter follows the pattern. #### Syntax ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} filter_[]= ``` Multiple filters for different fields are logically combined with **AND**. If multiple filters are specified for the same field, the API interprets them as an **OR** combination. ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ?filter_eq[status]=open &filter_gte[createdAt]=2024-12-01T00:00:00Z &filter_lte[createdAt]=2025-01-05T23:59:59Z ``` #### Supported filter operations | **Operation** | **Meaning** | | ------------------ | ------------------------------------------- | | `eq` | Equality (`=`) | | `neq` | Inequality (`!=`) | | `lt` | Less than (`<`) | | `lte` | Less than or equal (`≤`) | | `gt` | Greater than (`>`) | | `gte` | Greater than or equal (`≥`) | | `beginsWith` | Begins with | | `endsWith` | Ends with | | `contains` | Contains | | `notContains` | Does not contain | | `filter_within` | Applies to user-defined fields of type list | | `filter_notWithin` | Applies to user-defined fields of type list | #### Error codes | **Error code** | **Type** | **Description** | | -------------- | ------------------ | --------------------------------- | | 400 | `UnknownOperation` | The filter operation is not known | | 400 | `UnknownField` | The specified field is invalid | ### Full-text search Most endpoints support a full-text search via the optional URL parameter `textSearch`. This allows results to be filtered by a search term without having to specify explicit filter fields. The parameter can be specified multiple times — multiple values are combined with OR. The search is case-sensitive. #### Syntax ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} textSearch=&textSearch= ``` #### Example (single search term) ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/orders?textSearch=Mustermann ``` #### Example (multiple search terms) ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/orders?textSearch=Mustermann&textSearch=Berlin ``` *** ## Support Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: [Zum Kundenportal](https://websale.atlassian.net/servicedesk/customer/portal/6) Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.