AI RAG Indexer Tutorial

You can use the AI RAG Indexer Service to keep your vector database in sync with Emporix data and to discover which attributes are available for Retrieval-Augmented Generation (RAG) and filtering. The service supports the built-in product and order entity types, and custom entity types created in the Schema Service.

Follow this tutorial to learn how to create a RAG tool with indexable and filterable fields that you can use in an AI agent.

Prerequisites

• The OAuth2 access token must include the ai.agent_read and ai.agent_manage scopes.
• For built-in entity types, use product or order as the {type} path parameter.
• For custom entities, the custom type must exist in the Schema Service. The {type} in indexer URLs must match the config.entityType.

Note that removing a custom entity from the Emporix system results in automatic deletion of RAG tools that reference that entity.

How to prepare RAG indexing

1

Discover indexable fields

Before creating a RAG tool, call the AI RAG Indexer metadata endpoints for your entity type.

Call the Listing fields for RAG search endpoint to get the RAG fields.

Product

curl -L \
  --request GET \
  --url 'https://api.emporix.io/ai-rag-indexer/{{tenant}}/product/rag-metadata' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Accept: application/json'

Sample response:

[
  "code",
  "name.en",
  "labels.description.de",
  "mixins.additionalattributes.temperature",
  "segmentIds"
]

Order

curl -L \
  --request GET \
  --url 'https://api.emporix.io/ai-rag-indexer/{{tenant}}/order/rag-metadata' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Accept: application/json'

Sample response:

[
  "id",
  "status",
  "customer.email",
  "customer.firstName",
  "customer.lastName",
  "customer.company",
  "siteCode",
  "currency",
  "entries",
  "shippingAddress.city",
  "billingAddress.city"
]

Custom Entity

curl -L \
  --request GET \
  --url 'https://api.emporix.io/ai-rag-indexer/{{tenant}}/car-parts/rag-metadata' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Accept: application/json'

Sample response (field paths depend on your custom schema):

[
  "code",
  "name.en",
  "description.en",
  "mixins.carparts.brand",
  "mixins.carparts.oemNumber",
  "mixins.carparts.vehicleCompatibility",
  "mixins.carparts.specifications"
]

Replace the sample paths with the values returned by rag-metadata for your tenant. Mixin keys must match your Schema Service attribute definitions.

Use the response paths in the indexedFields[].key when you create a RAG tool in the upcoming step.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

2

Discover filterable fields

Call the Listing fields for vector search filtering endpoint to retrieve the field paths for filtering search.

Product

curl -L \
  --request GET \
  --url 'https://api.emporix.io/ai-rag-indexer/{{tenant}}/product/filter-metadata' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Accept: application/json'

Sample response:

[
  { "key": "code", "type": "string" },
  { "key": "id", "type": "string" },
  { "key": "published", "type": "boolean" },
  { "key": "segmentIds", "type": "list" }
]

Order

curl -L \
  --request GET \
  --url 'https://api.emporix.io/ai-rag-indexer/{{tenant}}/order/filter-metadata' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Accept: application/json'

Sample response:

[
  { "key": "id", "type": "string" },
  { "key": "status", "type": "string" },
  { "key": "customer.email", "type": "string" },
  { "key": "siteCode", "type": "string" },
  { "key": "currency", "type": "string" },
  { "key": "legalEntityId", "type": "string" }
]

Custom Entity

curl -L \
  --request GET \
  --url 'https://api.emporix.io/ai-rag-indexer/{{tenant}}/car-parts/filter-metadata' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Accept: application/json'

Sample response (field paths depend on your custom schema):

[
  { "key": "id", "type": "string" },
  { "key": "code", "type": "string" },
  { "key": "mixins.carparts.brand", "type": "string" },
  { "key": "mixins.carparts.category", "type": "string" },
  { "key": "mixins.carparts.vehicleMake", "type": "string" },
  { "key": "published", "type": "boolean" },
  { "key": "mixins.carparts.inStock", "type": "boolean" }
]

Use the returned field paths in filterFields[].key when creating a tool in the upcoming step.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

3

Create an AI tool using RAG functionality

When you know which fields to index and filter, call the Upserting tool endpoint to create or update a rag_emporix tool.

Set the toolId in the URL path (for example, rag-product, rag-order, or rag-car-parts). The indexedFields and filterFields are required for rag_emporix tools – specify the paths from the responses returned in previous steps:

• The indexedFields can use optional name aliases.
• For the filterFields, add relevant descriptions so that the agent knows when to apply the filters.

Product

curl --request PUT \
  'https://api.emporix.io/ai-service/{{tenant}}/agentic/tools/rag-product' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Product Search RAG Tool",
    "type": "rag_emporix",
    "enabled": true,
    "config": {
      "prompt": "Use this tool when the user asks to find, compare, or look up products in the catalog.",
      "entityType": "product",
      "embeddingConfig": {
        "provider": "emporix_openai"
      },
      "indexedFields": [
        { "key": "code", "name": "Product code" },
        { "key": "name.en", "name": "English name" },
        { "key": "description.en", "name": "English description" }
      ],
      "filterFields": [
        {
          "key": "code",
          "name": "Product code",
          "description": "Exact product SKU or catalog code. Use when the user provides a specific product code."
        },
        {
          "key": "published",
          "name": "Published",
          "description": "Set to true when the user should only see products visible in the catalog."
        },
        {
          "key": "segmentIds",
          "name": "Customer segments",
          "description": "List of segment IDs. Use when results must be limited to products available for specific customer segments."
        }
      ]
    }
  }'

Order

curl --request PUT \
  'https://api.emporix.io/ai-service/{{tenant}}/agentic/tools/rag-order' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Order Search RAG Tool",
    "type": "rag_emporix",
    "enabled": true,
    "config": {
      "prompt": "Use this tool when the user asks to find, look up, or filter orders by customer, status, site, or other order details.",
      "entityType": "order",
      "embeddingConfig": {
        "provider": "emporix_openai"
      },
      "indexedFields": [
        { "key": "id", "name": "Order ID" },
        { "key": "status", "name": "Order status" },
        { "key": "customer.email", "name": "Customer email" },
        { "key": "customer.firstName", "name": "Customer first name" },
        { "key": "customer.lastName", "name": "Customer last name" },
        { "key": "customer.company", "name": "Customer company" },
        { "key": "siteCode", "name": "Site code" },
        { "key": "currency", "name": "Currency" }
      ],
      "filterFields": [
        {
          "key": "id",
          "name": "Order ID",
          "description": "Exact order identifier. Use when the user provides a specific order ID."
        },
        {
          "key": "status",
          "name": "Order status",
          "description": "Order status. Possible values: IN_CHECKOUT, CREATED, CONFIRMED, DECLINED, SHIPPED, COMPLETED."
        },
        {
          "key": "customer.email",
          "name": "Customer email",
          "description": "Customer email address. Use when the user asks for orders placed by a specific customer."
        },
        {
          "key": "siteCode",
          "name": "Site code",
          "description": "Site identifier. Use when results must be limited to orders from a specific shop or site."
        },
        {
          "key": "currency",
          "name": "Currency",
          "description": "Three-letter currency code (for example EUR or USD). Use when the user filters orders by currency."
        },
        {
          "key": "legalEntityId",
          "name": "Legal entity",
          "description": "Legal entity ID. Use when results must be limited to orders placed on behalf of a specific legal entity."
        }
      ]
    }
  }'

Custom Entity

curl --request PUT \
  'https://api.emporix.io/ai-service/{{tenant}}/agentic/tools/rag-car-parts' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Car Parts Search",
    "type": "rag_emporix",
    "enabled": true,
    "config": {
      "prompt": "Use this tool when the user asks to find automotive parts by name, part number, OEM reference, or vehicle fitment (make, model, year).",
      "entityType": "car-parts",
      "embeddingConfig": {
        "provider": "emporix_openai"
      },
      "indexedFields": [
        { "key": "code", "name": "Part number" },
        { "key": "name.en", "name": "English part name" },
        { "key": "description.en", "name": "English description" },
        { "key": "mixins.carparts.brand", "name": "Brand" },
        { "key": "mixins.carparts.oemNumber", "name": "OEM number" },
        { "key": "mixins.carparts.vehicleCompatibility", "name": "Vehicle compatibility" },
        { "key": "mixins.carparts.specifications", "name": "Technical specifications" }
      ],
      "filterFields": [
        {
          "key": "code",
          "name": "Part number",
          "description": "SKU or catalog part number. Use when the user provides an exact part number."
        },
        {
          "key": "mixins.carparts.oemNumber",
          "name": "OEM number",
          "description": "Original equipment manufacturer part number. Use when the user searches by OEM reference."
        },
        {
          "key": "mixins.carparts.brand",
          "name": "Brand",
          "description": "Manufacturer or aftermarket brand (for example Bosch, Brembo, Mann)."
        },
        {
          "key": "mixins.carparts.category",
          "name": "Category",
          "description": "Part category such as brakes, filters, engine, suspension, or electrical."
        },
        {
          "key": "mixins.carparts.vehicleMake",
          "name": "Vehicle make",
          "description": "Vehicle manufacturer (for example Volkswagen, BMW, Ford). Use for fitment filtering."
        },
        {
          "key": "mixins.carparts.vehicleModel",
          "name": "Vehicle model",
          "description": "Vehicle model (for example Golf, 3 Series). Use together with make and year."
        },
        {
          "key": "mixins.carparts.vehicleYear",
          "name": "Model year",
          "description": "Production or model year (for example 2018). Use for fitment filtering."
        },
        {
          "key": "mixins.carparts.condition",
          "name": "Condition",
          "description": "Part condition. Possible values: NEW, REFURBISHED, USED."
        },
        {
          "key": "published",
          "name": "Published",
          "description": "Set to true when the user should only see parts available in the catalog."
        },
        {
          "key": "mixins.carparts.inStock",
          "name": "In stock",
          "description": "Set to true when the user asks for parts that can be ordered now."
        }
      ]
    }
  }'

Align indexedFields and filterFields with the output of rag-metadata and filter-metadata for your tenant.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

4

Trigger a reindex job

When the tool is configured, call the Creating a reindex job endpoint to regenerate embeddings for the selected entity type. The reindex endpoint currently performs a full rebuild.

Product

curl -L \
  --request POST \
  --url 'https://api.emporix.io/indexing/{{tenant}}/reindex-jobs' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "entityType": "PRODUCT",
    "rag": true
  }'

For products, set "rag": true so the reindex job generates vector embeddings for your rag_emporix tool, using the indexedFields defined in the tool configuration. Without this flag, only the storefront search index is rebuilt; the vector database used for RAG retrieval is not updated.

Order

curl -L \
  --request POST \
  --url 'https://api.emporix.io/indexing/{{tenant}}/reindex-jobs' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "entityType": "ORDER",
    "rag": true
  }'

For orders, set "rag": true so the reindex job generates vector embeddings for your rag_emporix tool, using the indexedFields defined in the tool configuration.

Custom Entity

curl -L \
  --request POST \
  --url 'https://api.emporix.io/indexing/{{tenant}}/reindex-jobs' \
  --header 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "entityType": "CAR_PARTS"
  }'

The service fetches every entity of the specified type (product, order, or custom entity type). Embeddings are generated per entity and vector database records are updated. You receive a 201 or 200 response with a reindex job ID, which allows you to track the progress.

Reindexing is a computationally expensive and time-consuming operation, especially for large catalogs or high order volumes. It may significantly increase infrastructure costs, processing time, and overall system load. For this reason, perform reindexing only when truly necessary — for example, after major configuration changes, embedding model updates, or structural schema modifications. Avoid triggering it frequently or without clear intent.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

5

Attach the tool to an agent

Assign the tool ID (for example, rag-product, rag-order, or rag-car-parts) to an AI agent so it can be invoked during agentic chat. Use the Upserting agent endpoint or configure the agent in Management Dashboard.

For broader agent setup and chat flows, see the AI Service Tutorial.