Create Index

Overview

Before you can start adding products and performing searches, you need to create an index. An index is a collection that stores and organizes your product data for efficient search and retrieval. The Marqo Ecommerce API provides specialized model types optimized for different retail sectors.

This page covers the full index lifecycle: creating an index, listing your indexes, checking the status and details of one index, and deleting an index. To change how an index searches and indexes documents after it exists, see Configure Index and Search Settings.

What is an Index?

An index serves as the foundation for your search functionality. It defines:

Data Structure: How your product information is organized and stored
Search Capabilities: What types of searches and recommendations are available
Model Optimization: Which AI models are used for understanding and matching your products

Think of an index as a smart catalog that not only stores your products but also understands their content, relationships, and context to deliver relevant search results.

Model Types

The modelType you choose when creating an index selects the embedding model and default settings for the index. There are three model types:

`ecommerce`

Best for: General retail products across various categories
Optimized for: Broad product catalogs, multi-category stores, marketplace platforms
Use cases: Electronics, home goods, books, general merchandise
Understands: Product text and product images

`fashion`

Best for: Fashion, apparel, and style-related products
Optimized for: Clothing, accessories, footwear, fashion items
Use cases: Fashion retailers, clothing brands, style platforms
Understands: Product text and product images, with enhanced visual similarity for apparel

`text`

Best for: Catalogs where search should rely on text only
Optimized for: Product titles, descriptions and attributes; image URLs are indexed as plain text rather than as images
Use cases: Catalogs without product imagery, or where images are not useful for search

Custom models

Marqo can train a model on your own catalog to understand your product attributes, terminology and customer search patterns. A custom model is not a separate modelType. Instead, you pass the model name the Marqo team gives you in the optional model field alongside one of the three model types above. Please reach out to Marqo for more information.

API Reference

All index management endpoints take your API key as a bearer token:

Authorization: Bearer {api_key}

Create Index

Endpoint: POST https://ecom.marqo-ep.ai/api/v1/indexes

Headers:

Authorization: Bearer {api_key} - Your API key for authentication
Content-Type: application/json - Specify JSON content type

Request Body:

{
  "indexName": "<your-index-name>",
  "modelType": "ecommerce"
}

Parameters

Parameter	Type	Default	Description
`indexName`	string	Required	A unique name for your index. Up to 32 characters; lowercase letters, digits, hyphens and underscores only, and it must start with a letter or digit. Only the length is checked when the request is received; the remaining rules are enforced when the index is provisioned and are reported as `400 "Invalid request parameters: ..."`.
`modelType`	string	Required	The model type for your product catalog. One of `ecommerce`, `fashion` or `text`, exactly as written.
`model`	string	Default model for the `modelType`	Overrides the embedding model. Use this for a custom model provided by the Marqo team.
`tier`	string	`production`	Infrastructure tier. `staging` creates a smaller index (basic storage, no replicas) for development and testing; `production` uses the default infrastructure settings.
`allowExisting`	boolean	`false`	When `true`, an index that already exists with this name is reused and its configuration is brought up to date instead of returning `409 Conflict`.
`queueType`	string	`standard`	Delivery mode for the queue that feeds documents into the index. `standard` is the default; `fifo` processes documents strictly in the order they were submitted. Choose this at creation time: it cannot be changed through the configuration endpoint later.
`addDocsConfig`	object	Marqo defaults	Document indexing settings for the new index, such as which fields to embed or collapse on. Uses the same shape as the `addDocsConfig` block on the Configure Index page.
`pixelId`	string	None	The event tracking pixel customer ID to associate with the index. Linking is best effort: if the pixel is already linked to another index the existing link is kept, the index is still created, and no error is returned. Use Update a pixel account to move an existing link.

Example Request

cURL
JavaScript

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
  "indexName": "my-store-products",
  "modelType": "ecommerce"
}'

fetch("https://ecom.marqo-ep.ai/api/v1/indexes", {
  method: "POST",
  headers: {
    "Authorization": "Bearer {api_key}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    indexName: "my-store-products",
    modelType: "ecommerce",
  }),
});

Response

Index creation is asynchronous. The request returns as soon as the index has been scheduled, and the index is then built in the background, which typically takes 5 to 10 minutes.

{
  "indexName": "my-store-products",
  "status": "CREATING",
  "message": "Index my-store-products is being created. This typically takes 5-10 minutes."
}

Poll Get Index until indexStatus is READY before adding products or searching.

:::note A new index returns 404 at first Creation is asynchronous, and an index is only addressable on the management endpoints once its settings have been provisioned. Until then GET /indexes/{index_name} returns 404 with {"error": "Marqo settings not found for shop {system_account_id}-{index_name}"}.

Treat that 404 as "not ready yet" and keep polling. It does not mean the name was wrong or that creation failed. List Indexes shows the index before it becomes individually addressable, so use it to confirm creation started. :::

Errors

Status	Body	When
`400`	`{"error": "Invalid request parameters: ..."}`	A parameter is invalid, for example an `indexName` longer than 32 characters (`Index name <name> is too long (max 32 chars)`).
`409`	`{"error": "Index <name> already exists"}`	An index with this name already exists and `allowExisting` is not `true`.
`500`	`{"error": "Failed to create index: No <modelType> configuration found for system account: ..."}`	`modelType` is not one of `ecommerce`, `fashion` or `text`. The value is case sensitive, and an unrecognised one is reported as a server error rather than a validation error.
`500`	`{"error": "Failed to create index: ..."}`	The index could not be created for another reason. Contact Marqo if this persists.

List Indexes

Lists the indexes belonging to your account, with the lifecycle status of each.

Endpoint: GET https://ecom.marqo-ep.ai/api/v1/indexes

cURL
JavaScript

curl https://ecom.marqo-ep.ai/api/v1/indexes \
  -H "Authorization: Bearer {api_key}"

fetch("https://ecom.marqo-ep.ai/api/v1/indexes", {
  headers: {
    "Authorization": "Bearer {api_key}",
  },
});

Response

{
  "indexes": [
    {
      "name": "my-store-products",
      "status": "READY",
      "createdAt": "2025-09-01T12:00:00Z",
      "updatedAt": "2025-09-03T08:15:42Z"
    }
  ]
}

Field	Description
`name`	The index name.
`status`	Lifecycle status: `READY`, `CREATING`, `MODIFYING`, `DELETING`, `DELETED` or `FAILED`.
`createdAt`	ISO 8601 timestamp of when the index was created.
`updatedAt`	ISO 8601 timestamp of when the index configuration was last updated.

The listing is deliberately brief. Use Get Index for document counts, the model and other details.

Get Index

Returns the status and details of one index. Use it to check whether an index has finished creating.

Endpoint: GET https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}

cURL
JavaScript

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name} \
  -H "Authorization: Bearer {api_key}"

fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}", {
  headers: {
    "Authorization": "Bearer {api_key}",
  },
});

Response

The key fields are shown below. The full object contains further infrastructure and model details and may include additional fields.

{
  "indexName": "my-store-products",
  "indexStatus": "READY",
  "Created": "2025-09-01T12:00:00Z",
  "docs.count": "12840",
  "store.size": "3.1gb",
  "model": "Marqo/marqo-ecommerce-embeddings-L",
  "modelProperties": {
    "name": "Marqo/marqo-ecommerce-embeddings-L",
    "type": "open_clip",
    "dimensions": 1024
  },
  "marqoVersion": "2.13",
  "numberOfShards": 2,
  "numberOfReplicas": 1
}

Field	Description
`indexName`	The index name.
`indexStatus`	Lifecycle status, using the same values as List Indexes.
`Created`	ISO 8601 timestamp of when the index was created.
`docs.count`	Number of documents in the index, as a string.
`store.size`	Storage used by the index, as a string.
`model`	The embedding model the index was created with.
`modelProperties`	Details of that model, including its type and embedding dimensions.
`marqoVersion`	The Marqo version the index is running.

Errors

Status	Body	When
`404`	`{"error": "Marqo settings not found for shop {system_account_id}-{index_name}"}`	No index with this name exists in your account, it belongs to a different account, or it is still being provisioned.

Delete Index

Permanently deletes an index, all of its documents and its configuration.

warning

This action is irreversible. All indexed data is permanently lost.

Endpoint: DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}

cURL
JavaScript

curl -X DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name} \
  -H "Authorization: Bearer {api_key}"

fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer {api_key}",
  },
});

Response

A 200 OK with a JSON string body:

"Index deleted successfully"

Deletion runs in the background. The index reports DELETING in List Indexes until it is gone.

Errors

Status	When
`404`	No index with this name exists in your account, it belongs to a different account, or it is still being provisioned. Body: `{"error": "Marqo settings not found for shop {system_account_id}-{index_name}"}`.
`409`	The index has alias routing configured and is directing traffic to another index. Contact Marqo before deleting it.

Best Practices

Index Naming

Use descriptive names that reflect your business or product category
Use lowercase letters, digits, hyphens and underscores only; avoid spaces
Keep names to 32 characters or fewer

Model Type Selection

Choose ecommerce for diverse product catalogs spanning multiple categories
Choose fashion specifically for apparel, accessories, and style-focused products
Choose text when product images should not influence search
Consider your primary product categories when making this decision

After Creating

Poll Get Index until indexStatus is READY before adding products
Use a staging tier index for development so production traffic is not affected

Next Steps

After creating your index, you can:

Add Products: Start populating your index with product data
Configure Index: Set default search parameters, collection behaviour and indexing options
Search Settings: Turn on SKU matching, out-of-stock handling and display names for facets
Configure Search: Set up search functionality for your customers
Enable Recommendations: Activate product recommendation features

Common Issues

Index Already Exists

If you try to create an index with a name that already exists, you'll receive a 409 Conflict error. Choose a different name, delete the existing index first, or pass "allowExisting": true to reuse it.

Invalid Model Type

Ensure you specify ecommerce, fashion or text exactly as shown. The API is case-sensitive.

Authentication Errors

Make sure your API key is valid and included in the Authorization header with the "Bearer " prefix.

Need Help? If you encounter any issues creating your index, please reach out to the Marqo team for support.

Overview​

What is an Index?​

Model Types​

ecommerce​

fashion​

text​

Custom models​

API Reference​

Create Index​

Parameters​

Example Request​

Response​

Errors​

List Indexes​

Response​

Get Index​

Response​

Errors​

Delete Index​

Response​

Errors​

Best Practices​

Index Naming​

Model Type Selection​

After Creating​

Next Steps​

Common Issues​

Index Already Exists​

Invalid Model Type​

Authentication Errors​

Overview

What is an Index?

Model Types

`ecommerce`

`fashion`

`text`

Custom models

API Reference

Create Index

Parameters

Example Request

Response

Errors

List Indexes

Response

Get Index

Response

Errors

Delete Index

Response

Errors

Best Practices

Index Naming

Model Type Selection

After Creating

Next Steps

Common Issues

Index Already Exists

Invalid Model Type

Authentication Errors