Manage Collections

The Collections API stores display metadata for the collections in your catalog: a human-readable name and any custom fields you want to attach to a collection (an image, a priority, an alternative ID). Marqo's merchandising tools and your own UI read these records to show collection names instead of raw IDs.

These records do not control which products belong to a collection. Membership comes from each product document: every product carries a productCollections array listing the collections it belongs to (see Add Products). When a shopper browses a collection, the collectionName in the request is matched against that field. If a different field was configured as your collections field when the index was created, membership is read from that field instead.

You only need this API if you want to attach a display name or other metadata to a collection ID. Collections referenced in productCollections are browsable whether or not a metadata record exists for them.

Collection metadata records belong to your account, not to a single index. The id of a record should match the value your products use in productCollections.

Prerequisites

• A Marqo Cloud account (sign up here)
• Your Marqo API key (find your API key guide)

All endpoints on this page authenticate with Authorization: Bearer {api_key}.

The collection record

Every endpoint that returns a collection uses this shape:

{
  "id": "summer-sale",
  "displayName": "Summer Sale",
  "metadata": {
    "category": "seasonal",
    "imageUrl": "https://example.com/summer-sale.jpg"
  },
  "createdAt": "2024-06-01T09:15:00.000000+00:00",
  "updatedAt": "2024-06-14T16:40:00.000000+00:00"
}

Field	Type	Description
id	String	The collection identifier. Matches the value used in your products' productCollections field.
displayName	String	Human-readable name for the collection. null if not set.
metadata	Object	Free-form key-value pairs. Values are stored as sent and are not validated. null if not set.
createdAt	String	ISO 8601 timestamp of when the record was written.
updatedAt	String	ISO 8601 timestamp of the last write.

Create or update collections

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

Creates metadata records for one or more collections in a single request. The body is an object with a collections array. If a record with the same id already exists it is replaced in full (upsert): fields you omit are cleared, and createdAt and updatedAt are both set to the time of the request.

cURL

curl -X POST https://ecom.marqo-ep.ai/api/v1/collections \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "collections": [
      {
        "id": "summer-sale",
        "displayName": "Summer Sale",
        "metadata": {
          "category": "seasonal",
          "imageUrl": "https://example.com/summer-sale.jpg"
        }
      },
      {
        "id": "new-arrivals",
        "displayName": "New Arrivals"
      }
    ]
  }'

JavaScript

fetch("https://ecom.marqo-ep.ai/api/v1/collections", {
  method: "POST",
  headers: {
    "Authorization": "Bearer {api_key}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    collections: [
      {
        id: "summer-sale",
        displayName: "Summer Sale",
        metadata: {
          category: "seasonal",
          imageUrl: "https://example.com/summer-sale.jpg",
        },
      },
      {
        id: "new-arrivals",
        displayName: "New Arrivals",
      },
    ],
  }),
});

Note: Replace {api_key} with your API key.

Request body

Parameter	Type	Default	Description
collections	Array of objects	Required	The records to create or update.
collections[].id	String	Required	The collection identifier. Leading and trailing whitespace is removed before the record is stored. An id that is empty or only whitespace is not rejected: it is stored under an empty identifier, which no product document can match. Validate it before sending.
collections[].displayName	String	null	Human-readable name for the collection.
collections[].metadata	Object	null	Free-form key-value pairs for the collection.

Response

201 Created with an empty body. Use List collections or Get a collection to read the stored records back.

A body that does not match the shape above (for example a flat {"id": ...} object instead of a collections array, or an entry without id) is rejected with 422 Unprocessable Entity.

List collections

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

Returns every collection metadata record for your account.

cURL

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

JavaScript

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

Response

200 OK

{
  "collections": [
    {
      "id": "summer-sale",
      "displayName": "Summer Sale",
      "metadata": {
        "category": "seasonal",
        "imageUrl": "https://example.com/summer-sale.jpg"
      },
      "createdAt": "2024-06-01T09:15:00.000000+00:00",
      "updatedAt": "2024-06-14T16:40:00.000000+00:00"
    },
    {
      "id": "new-arrivals",
      "displayName": "New Arrivals",
      "metadata": null,
      "createdAt": "2024-06-01T09:15:00.000000+00:00",
      "updatedAt": "2024-06-01T09:15:00.000000+00:00"
    }
  ]
}

collections is an empty array when no records exist.

Get a collection

GET https://ecom.marqo-ep.ai/api/v1/collections/{collection_id}

Returns the metadata record for a single collection.

cURL

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

JavaScript

fetch("https://ecom.marqo-ep.ai/api/v1/collections/summer-sale", {
  method: "GET",
  headers: {
    "Authorization": "Bearer {api_key}",
  },
});

Note: Replace summer-sale with your collection ID.

Response

200 OK

{
  "id": "summer-sale",
  "displayName": "Summer Sale",
  "metadata": {
    "category": "seasonal",
    "imageUrl": "https://example.com/summer-sale.jpg"
  },
  "createdAt": "2024-06-01T09:15:00.000000+00:00",
  "updatedAt": "2024-06-14T16:40:00.000000+00:00"
}

404 Not Found when no record exists for that ID:

{
  "error": "Collection 'summer-sale' not found"
}

Delete collections

DELETE https://ecom.marqo-ep.ai/api/v1/collections

Deletes the metadata records for one or more collections in a single request. Only the metadata records are removed. Product documents and their productCollections values are not affected, and the collections remain browsable.

cURL

curl -X DELETE https://ecom.marqo-ep.ai/api/v1/collections \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["summer-sale", "new-arrivals"]}'

JavaScript

fetch("https://ecom.marqo-ep.ai/api/v1/collections", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer {api_key}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ids: ["summer-sale", "new-arrivals"],
  }),
});

Request body

Parameter	Type	Default	Description
ids	Array of strings	Required	The collection IDs whose metadata records should be deleted. An empty array is accepted and deletes nothing.

Response

204 No Content with an empty body. IDs that have no metadata record are ignored, so the response does not tell you which IDs existed. Use Get a collection first if you need to know. An empty ids array also returns 204, so a 204 on its own is not confirmation that anything was deleted.

Delete a collection

DELETE https://ecom.marqo-ep.ai/api/v1/collections/{collection_id}

Deletes the metadata record for a single collection. As with the batch endpoint, product documents are not affected.

cURL

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

JavaScript

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

Note: Replace summer-sale with your collection ID.

Response

204 No Content with an empty body.

404 Not Found when no record exists for that ID:

{
  "error": "Collection 'summer-sale' not found"
}