Catalog Schema API

This is for:

Developer
Important

The Catalog Schema and Ingestion APIs are currently in closed beta. Contact your Coveo representative to learn about these APIs and how to get involved.

The Catalog Schema and Ingestion APIs offer a streamlined approach to managing catalog data indexing and updates, simplifying data integration and maintenance within a Coveo organization.

The Catalog Schema API serves as your starting point by letting you define the metadata keys you’ll want to index in your Coveo organization. This schema is used to validate your data as it’s being indexed. Additionally, the Catalog Schema API automates resource creation tasks previously done manually, such as setting up your Catalog source, catalog entity, and catalog configuration.

The Catalog Schema API lets you define the structure of your product data. This schema-driven approach ensures that all incoming data is validated against the defined structure, reducing errors and improving data quality.

Resource creation

The Catalog Schema API is designed to simplify the process of creating and managing a commerce-focused Coveo organization. It removes manual configuration tasks and streamlines the onboarding process.

When a schema is created, the Catalog Schema API automatically sets up the underlying resources needed within the Coveo organization. For each schema, the following related resources are automatically created:

  • A Catalog source that will store your catalog data.

  • All Coveo commerce standard fields and their mappings are automatically created in the Coveo organization.

  • All of the custom fields defined in the schema, if they don’t already exist.

    Notes

    • If a custom field already exists in your organization, but its definition differs from what’s provided in your schema, the process won’t update the existing field. Any attempt to ingest data into a field whose definition differs from your schema will result in an ingestion error.

    • Don’t modify the following field options for automatically created fields:

      • Field type

      • Multi-value facet

  • A catalog entity.

  • A catalog configuration.

Limitations

This section outlines the current limitations of using the Catalog Ingestion and Schema APIs to manage your catalog data:

  • The APIs currently only support the ingestion of Product catalog object items. This means that if your catalog data contains items of the Variant or Availability types, you can’t use these APIs yet.

  • The APIs don’t currently support the ingestion of dictionary fields. However, the team is actively working on an approach to handle them.

Leading practices

When using the Catalog Schema and Ingestion APIs, consider the following leading practices:

  • Always create a schema using the Catalog Schema API before attempting to ingest data.

  • Leverage the automated nature of these APIs to reduce manual interventions to the following resources, as these APIs manage those configurations automatically:

    • Automatically created fields.

      Important

      Avoid changing the Type and Multi-value facet options for fields that are created automatically. You can modify other field options as needed.

    • Automatically created Catalog sources.

    • Automatically created Catalog entities.

    • Automatically created Catalog configurations.

  • Don’t apply indexing pipeline extensions (IPEs) or modify the source mappings for the sources created by the Catalog Schema API.

Usage

You must define a schema for all of the catalog objects you want in your Coveo organization. Currently, only the PRODUCT object type is supported.

Schemas are also tied to a specific locale. For example, if you are indexing products for a Canadian market in both English and French, you must create two separate product schemas: one for en-CA and another for fr-CA.

Once a schema is created, the second step is to define the custom data you want to index. Defining custom data in a schema is only relevant for the data that you want to index which isn’t already covered by the system and standard commerce fields provided by Coveo. Coveo already enforces a schema to ensure that the required data is present in the product data you ingest and that they comply with the specified data types and formats.

Expand the following sections to reveal a table that lists the fields that are enforced by the Coveo schema, and for which you don’t need to define a schema. The Coveo Platform will reject any schema that uses these field names.

Standard commerce fields enforced by the Coveo schema

Standard commerce fields are crucial for the proper functioning of Coveo’s commerce features, such as Coveo Machine Learning (Coveo ML) models and event enrichment.

Field Description

ec_product_id

The product’s unique identifier within a single source.

ec_name

The product’s name.

ec_description

The product’s description.

ec_shortdesc

A short description of the product.

ec_price

The product’s base price.

ec_item_group_id

An identifier used for product grouping.

ec_thumbnails

A collection of lower-resolution product images used for faster page load time (URL format).

ec_images

A collection of high-resolution product images used to view product details (URL format).

ec_brand

The product’s brand.

ec_cogs

The product’s cost of goods sold (COGS). Used to calculate the product margin.
System fields enforced by the Coveo schema

System fields are required by the Coveo index and apply to all sources. They’re automatically created and, for the most part, automatically filled by the Coveo Platform.

Field

attachmentdepth

attachmentparentid

author

clickableuri

collection

concepts

containsattachment

date

documentid

fileextension

filename

filetype

indexeddate

isattachment

isrecord

isreference

language

metadatasampling

month

objecttype

ocrpages

openwithquickview

orderingid

parentid

parents

permanentid

primaryid

printableuri

rowid

size

source

title

topparent

topparentid

transactionid

uri

urihash

wordcount

year

For all the other metadata that you want to index, you must define custom fields in your schema. For example, if you want to index product attributes like product_size, available_colors, or gender, you would include these fields in your schema definition.

Using the Catalog Schema API, you can:

Define a catalog schema

Defining a catalog schema is a two-step process:

Step 1: Create a catalog schema

The first step in defining your catalog schema is to create it using the Catalog Schema API. You must create a schema for all of the catalog object and locale combinations you want in your Coveo organization.

For example, if you want to index products for a Canadian market in both English and French, you must create two separate product schemas: one for en-CA and another for fr-CA.

Important

Currently, only the PRODUCT object type is supported.

To create a catalog schema, use the following endpoint of the Catalog Schema API:

POST /rest/organizations/<ORGANIZATION_ID>/catalogs/unstable/schemas HTTP/1.1

  • Where <ORGANIZATION_ID> is the unique identifier of your Coveo organization. To learn how to find the organization ID, see Find your organization ID.

Note

To use this endpoint, you must have the Edit access level for the Catalog setup domain.

In the request body, you must provide a JSON object that defines the schema.

Example request body:

{
  "name": "Barca en-CA-CAD", 1
  "objectTypes": [
    {
      "name": "PRODUCT" 2
    }
  ]
}
1 The top-level name key is a human-readable identifier for the schema. You must create a schema for each locale you’re supporting, so you should include the locale in the name. This name will be used for the following resources that are automatically created when the schema is created:
2 The name in the objectTypes property specifies the type of catalog object that you’re defining for this array. Currently, only PRODUCT is supported.

Response

The response to a successful schema creation request includes the details of the created schema, including its unique identifier and the unique identifier of the source that was automatically created.

Example response:

{
  "id": "XXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", 1
  "name": "Barca en-CA-CAD",
  "objectTypes": [
    {
      "name": "PRODUCT"
    }
  ],
  "setup": {
    "sourceIds": [
      "YYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY" 2
    ]
  }
}
1 The id is the unique identifier of the created schema. You will need this ID for subsequent API calls that involve this schema.
2 The sourceIds array contains the unique identifier of the Catalog source that was automatically created when the schema was created.

Step 2: Define custom fields in the catalog schema

Now that you’ve created your catalog schema, the next step is to define the custom data you want to index that isn’t already covered by the system and standard commerce fields provided by Coveo.

To add custom data to an existing catalog schema, use the following endpoint of the Catalog Schema API:

PUT /rest/organizations/<ORGANIZATION_ID>/catalogs/unstable/schemas/<SCHEMA_ID>/object-types/<OBJECT_TYPE>/custom-fields?forceUpdate=<true|false> HTTP/1.1

Where:

  • <ORGANIZATION_ID> is the unique identifier of your Coveo organization. To learn how to find the organization ID, see Find your organization ID.

  • <SCHEMA_ID> is the unique identifier of the schema that you want to update.

  • <OBJECT_TYPE> is the type of catalog object that the field you’re adding pertains to. Currently, only PRODUCT is supported.

  • (optional) The forceUpdate query parameter indicates whether to update an existing field if a field with the same name already exists in the schema. The default value is false. Use true to update the existing field with the new definition provided in the request body.

    Warning

    Be cautious when using the forceUpdate parameter. Fields are index-wide, meaning that if the updated field is used in multiple sources, the change will apply to all of them. This can have unintended consequences if the new definition is not compatible with the existing data or usage.
Note

To use this endpoint, you must have the following privileges:

In the request body, you must provide a JSON object that defines the fields to add to the schema.

Example request body:

[
  {
    "name": "product_size", 1
    "type": {
      "dataType": "INTEGER_32", 2
      "multiValue": false 3
    }
  },
  {
    "name": "available_colors",
    "type": {
      "dataType": "STRING",
      "multiValue": true
    }
  },
  {
    "name": "geolocation",
    "type": {
      "dataType": "DECIMAL",
      "multiValue": false
    }
  },
  {
    "name": "added_date",
    "type": {
      "dataType": "DATE",
      "multiValue": false
    }
  },
  {
    "name": "timestamp",
    "type": {
      "dataType": "INTEGER_64",
      "multiValue": false
    }
  }
]
1 The name property specifies the name of the custom metadata key to index from your catalog data. For example, if your catalog data has a product_size metadata that you want to index, set name to product_size. This creates a corresponding Coveo field named product_size. The example above adds 5 new fields: product_size, available_colors, geolocation, added_date, and timestamp.

Custom field names must:

  • Not use the ec_ prefix, as this is reserved for Coveo’s standard fields.

  • Have different names than the system fields that are automatically created and filled by the Coveo Platform.

  • Only contain lowercase alphanumeric characters and underscores (_).
2 dataType specifies the type of data for the possible values the metadata key can have. Allowed values are:

  • STRING: For text values. For example, red, blue, or green.

  • INTEGER_32: For 32-bit integer values. For example, 42 or 100.

  • DECIMAL: For floating-point values. For example 3.14 or 2.718.

  • DATE: For date values in the ISO 8601 format. For example, 2025-03-15.

  • INTEGER_64: For 64-bit integer values. For example, 8304567890123.
3 multiValue indicates whether the key can have multiple values. For example, if available_colors can have multiple colors, such as red, blue, or green, you would set multiValue to true.

Allowed values are true or false.

multiValue can only be set to true for metadata of the STRING data type.

Not complying with these rules will result in an error when you try to create the schema. A successful response (200 OK) indicates that the fields have been added to the schema.

Update a catalog schema

The Catalog Schema API allows you to update existing catalog schemas. You can either add or remove specific fields.

Add fields to an existing catalog schema

To add new fields to an existing catalog schema, use the following endpoint of the Catalog Schema API:

PUT /rest/organizations/<ORGANIZATION_ID>/catalogs/unstable/schemas/<SCHEMA_ID>/object-types/<OBJECT_TYPE>/custom-fields?forceUpdate=<true|false> HTTP/1.1

Where:

  • <ORGANIZATION_ID> is the unique identifier of your Coveo organization. To learn how to find the organization ID, see Find your organization ID.

  • <SCHEMA_ID> is the unique identifier of the schema that you want to update.

  • <OBJECT_TYPE> is the type of catalog object that the field you’re adding pertains to. Currently, only PRODUCT is supported.

  • (optional) The forceUpdate query parameter indicates whether to update an existing field if a field with the same name already exists in the schema. The default value is false. Use true to update the existing field with the new definition provided in the request body.

    Warning

    Be cautious when using the forceUpdate parameter. Fields are index-wide, meaning that if the updated field is used in multiple sources, the change will apply to all of them. This can have unintended consequences if the new definition is not compatible with the existing data or usage.
Note

To use this endpoint, you must have the following privileges:

In the request body, you must provide a JSON object that defines the fields to add to the schema.

Example request body:

[
  {
    "name": "product_size", 1
    "type": {
      "dataType": "INTEGER_32", 2
      "multiValue": false 3
    }
  },
  {
    "name": "available_colors",
    "type": {
      "dataType": "STRING",
      "multiValue": true
    }
  },
  {
    "name": "geolocation",
    "type": {
      "dataType": "DECIMAL",
      "multiValue": false
    }
  },
  {
    "name": "added_date",
    "type": {
      "dataType": "DATE",
      "multiValue": false
    }
  },
  {
    "name": "timestamp",
    "type": {
      "dataType": "INTEGER_64",
      "multiValue": false
    }
  }
]
1 The name property specifies the name of the custom metadata key to index from your catalog data. For example, if your catalog data has a product_size metadata that you want to index, set name to product_size. This creates a corresponding Coveo field named product_size. The example above adds 5 new fields: product_size, available_colors, geolocation, added_date, and timestamp.

Custom field names must:

  • Not use the ec_ prefix, as this is reserved for Coveo’s standard fields.

  • Have different names than the system fields that are automatically created and filled by the Coveo Platform.

  • Only contain lowercase alphanumeric characters and underscores (_).
2 dataType specifies the type of data for the possible values the metadata key can have. Allowed values are:

  • STRING: For text values. For example, red, blue, or green.

  • INTEGER_32: For 32-bit integer values. For example, 42 or 100.

  • DECIMAL: For floating-point values. For example 3.14 or 2.718.

  • DATE: For date values in the ISO 8601 format. For example, 2025-03-15.

  • INTEGER_64: For 64-bit integer values. For example, 8304567890123.
3 multiValue indicates whether the key can have multiple values. For example, if available_colors can have multiple colors, such as red, blue, or green, you would set multiValue to true.

Allowed values are true or false.

multiValue can only be set to true for metadata of the STRING data type.

Not complying with these rules will result in an error when you try to create the schema. A successful response (200 OK) indicates that the fields have been added to the schema.

Delete a field from an existing catalog schema

To delete a field from an existing catalog schema, use the following endpoint of the Catalog Schema API:

DELETE /rest/organizations/<ORGANIZATION_ID>/catalogs/unstable/schemas/<SCHEMA_ID>/object-types/<OBJECT_TYPE>/custom-fields/<FIELD_NAME> HTTP/1.1

Where:

  • <ORGANIZATION_ID> is the unique identifier of your Coveo organization. To learn how to find the organization ID, see Find your organization ID.

  • <SCHEMA_ID> is the unique identifier of the schema that you want to update.

  • <OBJECT_TYPE> is the type of catalog object that the field you’re deleting pertains to. Currently, only PRODUCT is supported.

  • <FIELD_NAME> is the name of the custom metadata key you want to delete. For example, to delete the product_size field, set <FIELD_NAME> to product_size.

Note

To use this endpoint, you must have the Edit access level for the Catalog setup domain.

A successful response (200 OK) indicates that the field has been deleted from the schema.

Note

Deleting a field from a schema doesn’t delete the corresponding field in your Coveo organization.

View catalog schemas

The Catalog Schema API allows you to view existing catalog schemas in your Coveo organization.

View all catalog schemas

Viewing catalog schemas is useful for obtaining the unique identifiers of existing schemas, which you will need for subsequent API calls that involve those schemas.

To view the existing catalog schemas in your Coveo organization, use the following endpoint of the Catalog Schema API:

GET /rest/organizations/<ORGANIZATION_ID>/catalogs/unstable/schemas HTTP/1.1

Where <ORGANIZATION_ID> is the unique identifier of your Coveo organization. To learn how to find the organization ID, see Find your organization ID.

Note

To use this endpoint, you must have the View access level for the Catalog setup domain.

Response

The response to a successful request includes the details of all the catalog schemas defined in your Coveo organization.

Example response:

{
  "items": [
    {
      "id": "XXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", 1
      "name": "Barca en-CA-CAD", 2
      "setup": {
        "sourceIds": [
          "YYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY" 3
        ]
      }
    },
    {
      "id": "XXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "name": "Barca fr-CA-CAD",
      "setup": {
        "sourceIds": [
          "YYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY"
        ]
      }
    }
  ]
}
1 The id is the unique identifier of the returned schema.
2 The name is the human-readable identifier of the returned schema.
3 The sourceIds array contains the unique identifier of the Catalog source that was automatically created when the schema was created.

View the fields of a specific catalog schema

To view the fields of a specific catalog schema, use the following endpoint of the Catalog Schema API:

GET /rest/organizations/<ORGANIZATION_ID>/catalogs/unstable/schemas/<SCHEMA_ID>/object-types/<OBJECT_TYPE>/custom-fields?page=<PAGE>&perPage=<PER_PAGE> HTTP/1.1

Where:

  • <ORGANIZATION_ID> is the unique identifier of your Coveo organization. To learn how to find the organization ID, see Find your organization ID.

  • <SCHEMA_ID> is the unique identifier of the schema whose fields you want to view.

  • <OBJECT_TYPE> is the type of catalog object whose fields you want to view. Currently, only PRODUCT is supported.

  • <PAGE> (optional) is the zero-based index of the page of results to return. The default value is 0, which represents the first page.

  • <PER_PAGE> (optional) is the number of results to return per page. The default value is 10.

Note

To use this endpoint, you must have the View access level for the Catalog setup domain.

Response

The response to a successful request includes the details of the fields defined in the specified schema, as well as pagination information.

Example response:

{
  "pagination": {
    "page": 0,
    "perPage": 10,
    "totalItems": 5,
    "totalPages": 1
  },
  "items": [
    {
      "name": "product_size",
      "type": {
        "dataType": "INTEGER_32",
        "multiValue": false
      }
    },
    {
      "name": "available_colors",
      "type": {
        "dataType": "STRING",
        "multiValue": true
      }
    },
    {
      "name": "geolocation",
      "type": {
        "dataType": "DECIMAL",
        "multiValue": false
      }
    },
    {
      "name": "added_date",
      "type": {
        "dataType": "DATE",
        "multiValue": false
      }
    },
    {
      "name": "timestamp",
      "type": {
        "dataType": "INTEGER_64",
        "multiValue": false
      }
    }
  ]
}

Delete a catalog schema

To delete a catalog schema, you must use the following endpoint of the Catalog Schema API:

DELETE /rest/organizations/<ORGANIZATION_ID>/catalogs/unstable/schemas/<SCHEMA_ID> HTTP/1.1

Where:

  • <ORGANIZATION_ID> is the unique identifier of your Coveo organization. To learn how to find the organization ID, see Find your organization ID.

  • <SCHEMA_ID> is the unique identifier of the schema you want to delete.

Note

To use this endpoint, you must have the Edit access level for the Catalog setup domain.

A successful response (200 OK) indicates that the schema has been deleted.

Deleting a schema will also delete the following resources, which were automatically generated when the schema was created:

Note

Fields created in the Coveo organization when the schema was created won’t be deleted.

What’s next?

Once you’ve defined a schema, you can start ingesting product data that conforms to the defined structure using the Catalog Ingestion API.