Skip to main content

Merchandising API

Overview​

The Merchandising API gives you programmatic access to the merchandising you would otherwise manage in the Marqo console. Use it to script rule changes, sync rules from another system, run campaigns from your own tooling, or let an agent manage merchandising for you.

Everything the API writes is the same data the console edits. A rule saved through the API shows up in the console, and a console edit shows up in the API.

ResourceWhat it controlsPage
Global rulesDefault filters, boosts, recency and reinforcement learning for every query, collection or recommendation in a contextGlobal Rules
Trigger rulesPins, exclusions, boosts, filters, recency and scheduled overrides for one search query, collection or seed productTrigger Rules
SynonymsOne-way rewrites of a child phrase to its parent phraseSynonyms
RedirectsSending a search for a term straight to a URLRedirects
Recommendation widgetsNamed recommendation shelves, their rules and per-product seed rulesRecommendation Widgets

All endpoints live under:

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

{index_name} is the index name or an alias of it. The API serves ecommerce indexes only.

note

The API does not cover A/B tests, merchandising profiles, facet rules or merchandising settings such as the recency field. Manage those in the console. Rules that the console writes for a merchandising profile keep serving and are not visible through the API (see Merchandising profiles).

Authentication​

Send your API key as a bearer token:

  • Authorization: Bearer {api_key}

Keep the key server-side.

OperationMinimum key scope
GET (any read)Read
PUT, POST, PATCH, DELETERead + Write

A key whose scope is too narrow gets 403 insufficient_scope. Keys created before scopes existed are treated as Admin. Recommendation widgets must also be enabled for your account: every /widgets operation, reads included, returns 403 feature_not_enabled until they are.

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/search/triggers/running%20shoes \
-H "Authorization: Bearer {api_key}"

Contexts​

Rules belong to a context, which says where they apply:

ContextApplies toTrigger is
searchSearch requestsThe search query
collectionCollection pagesThe collection id
similarSimilar recommendationsThe seed product's document _id
complementaryComplementary recommendationsThe seed product's document _id
complete_the_lookComplete the Look recommendationsThe seed product's document _id

Recommendation widgets have their own rules and are not addressed by context (see Recommendation Widgets).

Triggers in the path​

A trigger, synonym phrase or redirect term is a single URL-encoded path segment. Encode it with encodeURIComponent or your language's equivalent, so a / in it is sent as %2F and a % as %25:

ValuePath segment
running shoesrunning%20shoes
50% off/sale50%25%20off%2Fsale
shirts w/sleevesshirts%20w%2Fsleeves

Triggers are case-insensitive and stored in a canonical form: leading and trailing whitespace removed, lower-cased and Unicode-normalised (NFC). /triggers/Summer-Sale and /triggers/summer-sale address the same rule set, and responses return "trigger": "summer-sale".

A few values can't be addressed and are refused with 400 validation_error:

  • A value that is blank once its edge whitespace is removed.
  • A value with a . or .. part between slashes (a/../b), or an empty part (a//b, /sale). A . inside a word is fine: v1.2 and ... are valid triggers.
  • A trigger that ends in / (it would collide with the /schedule-history path). Synonym parents and redirect terms may end in /.
  • A trigger longer than 256 characters, or longer than 960 bytes as UTF-8. Synonym phrases and redirect terms are at most 200 characters.
  • Bytes that aren't valid UTF-8, a NUL (%00) or a malformed escape such as %ZZ. The last two are refused at the edge with an HTML 400 page rather than a JSON error.

Read, edit, write back​

Writes replace the whole resource. To change one rule, read the resource, edit it and send the whole body back. Request bodies accept the read-only fields of the matching response, so you can send back exactly what you read:

  • Bookkeeping fields (revision, updatedAt, selected, requestedTrigger) are ignored.
  • Identity fields (context, trigger, productId, a redirect's term) must match the resource you are writing to, or the write fails with 400 validation_error. This stops a body read from one trigger being written over another by mistake.
  • Any other unknown field is rejected with 400 validation_error.

Writing back an unchanged body stores nothing and keeps the revision.

Field types are strict: an integer field takes a JSON integer (1.0 and "3" are refused), and strings are never coerced to numbers or booleans.

Revisions and concurrent edits​

Every resource has a revision, returned in the body and as the ETag response header. A revision is a hash of the resource's content, so it changes whenever the content changes (including through the console) and comes back to the same value after an exact undo.

Preconditions are optional:

HeaderEffect
If-Match: "{revision}"Write only if the resource is still at that revision. Otherwise 412 revision_mismatch and nothing changes.
If-None-Match: *On a PUT that can create, create only if the resource doesn't exist yet. Otherwise 412 revision_mismatch.
NeitherThe write is unconditional. The last write wins, even over an edit made in the console.
curl -X PUT https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/rules/search/triggers/running%20shoes \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-H 'If-Match: "9c41e07b2d5a4f3e8a1b6c7d0e2f4a5b"' \
-d '{"pins": [{"position": 1, "documentId": "sku-48213"}]}'

Notes:

  • If-Match takes one quoted revision. The weak form W/"…" is accepted, because compression at the edge can weaken an ETag. *, lists and "" are 400 validation_error.
  • Sending both headers is 400 conflicting_preconditions.
  • Only a PUT that can create (trigger rules, a redirect, a seed product's rules) takes If-None-Match. Any other write, including every DELETE, refuses it with 400 validation_error.
  • An empty If-Match or If-None-Match header is dropped before it reaches the API, so the write goes through unconditionally. If you don't have a revision, leave the header out deliberately.
  • GET ignores If-None-Match and always returns 200 with the body, never 304.
  • Writes to something under a parent that doesn't exist (a deleted widget's rules or seeds, a deleted synonym group's children) fail with the parent's 404, whatever the preconditions say.

Use preconditions when anything else (the console, another script, an agent) edits the same resources.

Pagination​

Lists that can grow large are paginated with limit and cursor:

ParameterDescription
limitMost items per page. Defaults to 20, at most 100 (synonyms: 10 and 25). Plain decimal digits only (01, +1 and 1.0 are refused).
cursorThe nextCursor from the previous page. Opaque and tied to the endpoint it came from; a garbled or foreign cursor is 400 invalid_cursor.

A response holds items and nextCursor, which is null on the last page. Pages aren't a snapshot: paging while others edit never repeats an item, but can miss one created behind the cursor. Redirects and a widget's seed products are bounded (500 each) and return in full.

When changes go live​

A write goes through three stages:

  1. Saved. The write returned 2xx. It is durable and every read returns it.
  2. Published. Rules are exported to the edge every five minutes, so a saved change is normally published within five minutes.
  3. Propagated. Edge caches then converge, typically within about 12 minutes plus the index's search response-cache TTL. This is an expected window, not a guarantee.

Redirects skip the export: search reads them directly, and edges cache an index's redirects for up to 10 minutes.

The API has no endpoint that reports whether a change is live. Atomicity covers the saved configuration: a change that spans several resources, such as deleting a widget with many seed rules, is saved as one step, but live traffic may briefly see part of it while it propagates.

Limits​

LimitDefaultError
Trigger rule sets per index (including widget seed rules and console profile rule sets)1000422 limit_max_triggers
Pins per rule set120422 limit_max_pins_per_trigger
Highest pin position120422 limit_max_pin_position
Exclusions per rule set5422 limit_max_excludes_per_trigger
Pins, exclusions, boosts and filters combined, per rule set125422 limit_max_rules_per_trigger
Filters per rule set10400 validation_error
Scheduled overrides per rule set20422 limit_max_scheduled_overrides_per_trigger
Seed products with rules per widget500422 limit_max_seeds_per_widget
Redirects per index500422 limit_max_redirects_per_index
Request body1 MiB400 resource_too_large

Limits are set by Marqo. Filters, scheduled overrides, seed products and redirects are fixed; the others can differ per index, and Marqo can raise them on request. No operation returns them; the 422 message names the list that overflowed and the index's limit.

Errors​

Every error the API returns has this shape:

{
"detail": {
"code": "revision_mismatch",
"message": "The resource has changed since revision \"3f9a1c\". Read it again and retry."
}
}

Branch on code; the message is for people and its wording can change. New codes can be added, so handle an unknown code by its HTTP status.

StatusCodesMeaning
400validation_errorThe body, a path parameter or a query parameter is invalid. The message names the field.
400invalid_schedule_window, widget_not_seeded, conflicting_preconditions, resource_too_large, invalid_cursorSee the relevant section.
401invalid_api_keyThe API key is missing, unknown or revoked.
403insufficient_scope, feature_not_enabledSee Authentication.
404index_not_found, rule_set_not_found, synonym_group_not_found, redirect_not_found, widget_not_found, seed_not_foundThe index or the resource doesn't exist for your account.
409trigger_is_synonym_child, child_has_rules, phrase_in_use, ambiguous_synonym_groupA synonym protection. See Synonyms.
409profile_rule_sets_exist, widget_delete_pending, widget_has_seeds, already_exists, merchandising_not_configuredThe write conflicts with existing state.
409concurrent_modificationOther writes to the index kept changing it while the request ran. Writes, and reads that combine several rows (lists, a widget, trigger rules), can return it. Retry after Retry-After.
412revision_mismatchA precondition failed. Nothing was written.
422limit_*A limit would be exceeded.
422widget_rules_required, seed_rules_requiredThe write would leave a hand-picked widget or a seed with no rules.
500widget_unreadableA stored widget can't be read. Nothing was written; contact Marqo support.
502upstream_errorThe API couldn't complete the request. The outcome is unknown.
503outcome_unknownThe request timed out. The outcome is unknown.
503delete_incompleteA widget delete stopped partway. Retry the DELETE after Retry-After.

409 merchandising_not_configured means merchandising hasn't been set up on the index, so rule and widget writes are refused (reads return empty or default resources, and synonym and redirect writes still work). Contact Marqo support to set it up.

Retrying​

  • Retry 409 concurrent_modification and 503 delete_incomplete unchanged, after the Retry-After interval.
  • After a timeout, 502 upstream_error or 503 outcome_unknown, the write may or may not have been applied. Sending it again applies it to the current state, so an unconditional PUT can overwrite someone else's change made in between. Send If-Match (or If-None-Match: * for a create) when others edit the same resources. A conditional retry may get 412 or 404 because its first attempt landed; GET the resource and compare.
  • A retried create that already landed returns 200 with the stored resource instead of 409 already_exists.
  • A retried DELETE whose first attempt landed returns the resource's own 404 (rule_set_not_found, widget_not_found and so on): treat that as done. index_not_found is not; it means the index itself is gone.
  • Any other 4xx needs the request or the state to change first.