Catalog management

Retrieve lists of catalogs and manage catalog details.

Retrieving the filtered and sorted list of catalogs

get

Get the filtered list of catalogs for the specified tenant. Also, sorting and paging options are available. If none are given, default values are used.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Manage catalog
: View catalog

Path parameters

tenantstringRequired

Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Example: saasdev2

Query parameters

namestringOptional

Search by the name of the catalog. If you want to search for the name in a specific locale, you can just append the .<locale>, for example use name.de.

Example: name

descriptionstringOptional

Search by description of the catalog. If you want to search for the name in a specific locale, you can just append the .<locale>, for example use description.de.

Example: description

publishedSitestringOptional

Search by a site name. The equal operator is used here, therefore the site name must match.

visibilityFromstring · dateOptional

Search by start date of the visibility of the catalog. It must follow the pattern yyyy-MM-dd.

Example: 2022-01-28

visibilityTostring · dateOptional

Search by end date of the visibility of the catalog. It must follow the pattern yyyy-MM-dd.

Example: 2022-01-28

metadataUpdatedAtstring · dateOptional

Search by last update date of the catalog. It must follow the pattern yyyy-MM-dd.

Example: 2022-01-28

pageNumberinteger · int32 · min: 1Optional

Page number to be retrieved. The number of the first page is 1. Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.

Default: 1

pageSizeinteger · int32 · min: 1Optional

Number of catalogs to be retrieved per page.

Default: 60

sortstringOptional

Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case. Sorting by name parameter works properly only if the Accept-Language header is set to a specific language or is empty with default language specified in the configuration service.

Example: name,description:asc

Header parameters

X-Total-CountbooleanOptional

This flag specifies if the API client should receive a X-Total-Count header with the total number of elements that match the search filter.

Default: false

Accept-LanguagestringOptional

List of properties used to sort the results, separated by commas. Possible values:

* - each internationalized field is returned as a map containing all available translations
en, en,de - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.
fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - each internationalized field is returned as a map containing translation specified by a header value. If translation is not available exception is thrown. This list must contains any possible extension for internationalized fields included in sort param.

Default: *Example: *, 'en', 'en,de,fr', 'en-EN', 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5'

Responses

200

The search was successful.

application/json

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

500

An unexpected error prevented the server from fulfilling the request.

application/json

get

/catalog/{tenant}/catalogs

GET /catalog/{tenant}/catalogs HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "3456454",
    "name": {
      "en": "This is a catalog"
    },
    "description": {
      "en": "This catalog is used as an example"
    },
    "status": "visible",
    "visibility": {
      "visible": true,
      "from": "2022-02-24T20:44:43.169Z",
      "to": "2023-07-24T20:44:43.169Z"
    },
    "publishedSites": [
      "Main"
    ],
    "categoryIds": [
      "3249485"
    ],
    "metadata": {
      "version": 1,
      "updatedAt": "2022-02-24T20:44:43.169Z",
      "createdAt": "2022-02-24T20:44:43.169Z"
    }
  }
]

Creating a catalog

post

Creates a new catalog based on the provided request payload, for the specified tenant.

Required scopes

catalog.catalog_manage

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Manage catalog
: View catalog

Path parameters

tenantstringRequired

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Example: saasdev2

Header parameters

Content-LanguagestringOptional

The Content-Language request HTTP header defines language(s) that can be used in the payload. Request body may contain only translations that are matching the languages specified in the header. Possible values:

* - request body may contain translations for all languages specified in tenant configuration. This is also the default behaviour if the header is not set.
en, en,de, fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - request body may contain only translations for languages specified in the header (if they are available in tenant configuration).

Note: For catalog requests, localized fields (such as name, description) must always be provided as maps of language codes to values, regardless of the Content-Language header value.

Default: *Example: `*`, `en`, `en,de,fr`, `en-EN`, `fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7`

Body

Payload for creating a new catalog

idstring · min: 1 · max: 66Optional

Custom catalog identifier. If not provided, it is automatically generated.

Pattern: ^[a-zA-Z0-9_-]$

nameone ofRequired

Name of the catalog. Must be provided as a map of language codes to translations.

stringOptional

descriptionone ofOptional

Description of the catalog. Must be provided as a map of language codes to translations.

stringOptional

publishedSitesstring[]Optional

List of site identifiers on which the catalog is published.

categoryIdsstring[]Optional

List of root category identifiers that are assigned to the catalog.

Responses

201

The catalog has been successfully created.

application/json

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

403

Permission denied due to insufficient rights.

application/json

409

Given resource already exists.

application/json

500

An unexpected error prevented the server from fulfilling the request.

application/json

post

/catalog/{tenant}/catalogs

POST /catalog/{tenant}/catalogs HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 241

{
  "name": {
    "en": "This is a catalog"
  },
  "description": {
    "en": "This catalog is used as an example"
  },
  "visibility": {
    "visible": true,
    "from": "2022-02-24T20:44:43.169Z",
    "to": "2023-07-24T20:44:43.169Z"
  },
  "publishedSites": [
    "Main"
  ],
  "categoryIds": [
    "3249485"
  ]
}

{
  "id": "text"
}

Retrieving all catalogs for category

get

Get all catalogs with the specified category that belong to the tenant.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Manage catalog
: View catalog

Path parameters

tenantstringRequired

Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Example: saasdev2

categoryIdstringRequired

The unique id of the category, that will be matched with the category identifiers stored on catalogs.

Example: 787323

Query parameters

pageNumberinteger · int32 · min: 1Optional

Page number to be retrieved. The number of the first page is 1. Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.

Default: 1

pageSizeinteger · int32 · min: 1Optional

Number of catalogs to be retrieved per page.

Default: 60

sortstringOptional

Example: name,description:asc

Header parameters

X-Total-CountbooleanOptional

This flag specifies if the API client should receive a X-Total-Count header with the total number of elements that match the search filter.

Default: false

Accept-LanguagestringOptional

List of properties used to sort the results, separated by commas. Possible values:

* - each internationalized field is returned as a map containing all available translations
en, en,de - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.
fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - each internationalized field is returned as a map containing translation specified by a header value. If translation is not available exception is thrown. This list must contains any possible extension for internationalized fields included in sort param.

Default: *Example: *, 'en', 'en,de,fr', 'en-EN', 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5'

Responses

200

The search was successful.

application/json

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

500

An unexpected error prevented the server from fulfilling the request.

application/json

get

/catalog/{tenant}/catalogs/categories/{categoryId}

GET /catalog/{tenant}/catalogs/categories/{categoryId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "text",
    "name": {},
    "description": {},
    "status": null,
    "visibility": {
      "visible": false,
      "from": "text",
      "to": "text"
    },
    "publishedSites": [
      "text"
    ],
    "metadata": {
      "version": 1,
      "updatedAt": "2026-01-30T05:43:06.829Z",
      "createdAt": "2026-01-30T05:43:06.829Z"
    },
    "categoryIds": [
      "text"
    ]
  }
]

Retrieving a catalog by id

get

Get the catalog with the specified unique id that belongs to the tenant.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Manage catalog
: View catalog

Path parameters

tenantstringRequired

Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Example: saasdev2

catalogIdstringRequired

The unique id of the catalog.

Example: 787323

Header parameters

Accept-LanguagestringOptional

List of language codes acceptable for the response. Possible values:

* - each internationalized field is returned as a map containing all available translations
en, en,de - each internationalized field is returned as a map containing translation specified by a header value. If translation is not supported by tenant configuration then exception is thrown. First language is the one with highest priority.
fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5 - each internationalized field is returned as a map containing translation specified by a header value. If translation is not available exception is thrown.

Default: *Example: *, 'en', 'en,de,fr', 'en-EN', 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5'

Responses

200

Catalog was successfully retrieved.

application/json

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

404

Resource cannot be found

application/json

500

An unexpected error prevented the server from fulfilling the request.

application/json

get

/catalog/{tenant}/catalogs/{catalogId}

GET /catalog/{tenant}/catalogs/{catalogId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "text",
  "name": {},
  "description": {},
  "status": null,
  "visibility": {
    "visible": false,
    "from": "text",
    "to": "text"
  },
  "publishedSites": [
    "text"
  ],
  "metadata": {
    "version": 1,
    "updatedAt": "2026-01-30T05:43:06.829Z",
    "createdAt": "2026-01-30T05:43:06.829Z"
  },
  "categoryIds": [
    "text"
  ]
}

Upserting a catalog

put

Update or create the specified catalog.

Required scopes

catalog.catalog_manage

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Manage catalog
: View catalog

Path parameters

tenantstringRequired

Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Example: saasdev2

catalogIdstringRequired

The unique id of the catalog.

Example: 787323

Body

Payload for updating a catalog.

nameone ofRequired

Name of the catalog. Must be provided as a map of language codes to translations.

stringOptional

descriptionone ofOptional

Description of the catalog. Must be provided as a map of language codes to translations.

stringOptional

publishedSitesstring[]Optional

List of site identifiers on which the catalog is published.

categoryIdsstring[]Optional

List of root category identifiers that are assigned to the catalog.

Responses

201

The catalog has been successfully created.

application/json

204

The catalog has been successfully updated.

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

403

Permission denied due to insufficient rights.

application/json

404

Resource cannot be found

application/json

409

Resource conflict

application/json

500

An unexpected error prevented the server from fulfilling the request.

application/json

put

/catalog/{tenant}/catalogs/{catalogId}

PUT /catalog/{tenant}/catalogs/{catalogId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 268

{
  "name": {
    "en": "This is the same catalog"
  },
  "description": {
    "en": "This catalog has been updated"
  },
  "visibility": {
    "visible": true,
    "from": "2022-02-24T20:44:43.169Z",
    "to": "2023-07-24T20:44:43.169Z"
  },
  "publishedSites": [
    "Main"
  ],
  "categoryIds": [
    "3249485"
  ],
  "metadata": {
    "version": 1
  }
}

{
  "id": "4239475"
}

Removing catalog

delete

Remove the specified catalog.

Required scopes

catalog.catalog_manage

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Manage catalog
: View catalog

Path parameters

tenantstringRequired

Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Example: saasdev2

catalogIdstringRequired

The unique id of the catalog.

Example: 787323

Responses

204

The catalog has been successfully removed.

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

403

Permission denied due to insufficient rights.

application/json

404

Resource cannot be found

application/json

500

An unexpected error prevented the server from fulfilling the request.

application/json

delete

/catalog/{tenant}/catalogs/{catalogId}

DELETE /catalog/{tenant}/catalogs/{catalogId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Partially updating a catalog

patch

Update the specified catalog, even partially.

Required scopes

catalog.catalog_manage

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Manage catalog
: View catalog

Path parameters

tenantstringRequired

Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Example: saasdev2

catalogIdstringRequired

The unique id of the catalog.

Example: 787323

Body

Payload for partially updating a catalog.

nameone ofOptional

Name of the catalog. Must be provided as a map of language codes to translations.

stringOptional

descriptionone ofOptional

Description of the catalog. Must be provided as a map of language codes to translations.

stringOptional

publishedSitesstring[]Optional

List of site identifiers on which the catalog is published.

categoryIdsstring[]Optional

List of root category identifiers that are assigned to the catalog.

Responses

204

The catalog has been successfully updated.

application/json

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

403

Permission denied due to insufficient rights.

application/json

500

An unexpected error prevented the server from fulfilling the request.

application/json

patch

/catalog/{tenant}/catalogs/{catalogId}

PATCH /catalog/{tenant}/catalogs/{catalogId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 268

{
  "name": {
    "en": "This is the same catalog"
  },
  "description": {
    "en": "This catalog has been updated"
  },
  "visibility": {
    "visible": true,
    "from": "2022-02-24T20:44:43.169Z",
    "to": "2023-07-24T20:44:43.169Z"
  },
  "publishedSites": [
    "Main"
  ],
  "categoryIds": [
    "3249485"
  ],
  "metadata": {
    "version": 1
  }
}

{}

PreviousAPI Reference NextModels

Last updated 1 day ago

Was this helpful?

Good night

hashtagRetrieving the filtered and sorted list of catalogs

hashtagCreating a catalog

hashtagRequired scopes

hashtagRetrieving all catalogs for category

hashtagRetrieving a catalog by id

hashtagUpserting a catalog

hashtagRequired scopes

hashtagRemoving catalog

hashtagRequired scopes

hashtagPartially updating a catalog

hashtagRequired scopes

Retrieving the filtered and sorted list of catalogs

Creating a catalog

Required scopes

Retrieving all catalogs for category

Retrieving a catalog by id

Upserting a catalog

Required scopes

Removing catalog

Required scopes

Partially updating a catalog

Required scopes