Skip to content
engage-ai

API reference

Search

Search products, knowledge documents and contacts with one query

For concepts and a walkthrough, read Search.

Search everything

GET/search

One ranked list across every searchable resource — products, knowledge documents and contacts today, more later without a new endpoint.

Matching is trigram-based, so it tolerates typos and partial words: ridgelne finds Ridgeline. It is not the semantic retrieval the reply engine uses — for "what would the AI answer with?", use POST /knowledge/preview, which searches meaning rather than spelling.

Not paginated, deliberately. A ranked answer is not a list you walk; page two of a relevance ordering is where the answers are not. limit is a ceiling (50 max), and the response to too many results is a better query.

A provider that fails degrades to no results of its type rather than failing the search, so a broken index cannot take the search box down.

Auth
Session token or API key

Query parameters

  • qstringrequired

    What to look for. Two characters minimum — one matches almost everything.

    Min 2 characters · Max 256 characters

  • typesstring

    Comma-separated: PRODUCT, DOCUMENT, CONTACT. Omit to search everything.

  • limitinteger

    Default 20 · Max 50

Response fields 200
  • querystringrequired
  • itemsSearchHit[]required
  • countsobjectrequired

    Hits per type before the limit — "3 products, 2 documents".

  • searchedenum[]required

    What was actually searched. Grows as resources become searchable.

    One of PRODUCT, DOCUMENT, CONTACT

SearchResults

  • querystringrequired
  • itemsSearchHit[]required
  • countsobjectrequired

    Hits per type before the limit — "3 products, 2 documents".

  • searchedenum[]required

    What was actually searched. Grows as resources become searchable.

    One of PRODUCT, DOCUMENT, CONTACT

SearchHit

  • typeenumrequired

    Which kind of record this is. Group by it, or link on it.

    One of PRODUCT, DOCUMENT, CONTACT

  • idstring (uuid)required

    The record’s own id — link straight to it.

  • titlestringrequired
  • subtitlestring | nullrequired

    A SKU and price, an email, a source type.

  • excerptstring | nullrequired

    The matching text, when the match was against a body rather than a name.

  • scorenumberrequired

    0–1, comparable across types, which is why the list can be one ranking.

  • updatedAtstring (date-time) | nullrequired
  • groupKeystring | nullrequired

    Identifies the underlying record where two types are views of one thing — a product and the knowledge document projected from it. Already collapsed in these results; exposed so a client can tell that a DOCUMENT hit belongs to a product.

Responses

  • 200Ranked hits across every type searched.
  • 401Missing, malformed, revoked or expired API key.
  • 404Not found, or not visible to this organization.
  • 422Request failed validation.
  • 429Rate limited.
  • 500Unexpected error. The correlationId ties it to our logs.
Request
curl "https://api.getengageai.app/search?q=waterproof+boots" \
  -H "Authorization: Bearer $ENGAGE_API_KEY"
Response · 200
{
  "query": "waterproof boots",
  "items": [
    {
      "type": "PRODUCT",
      "id": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
      "title": "Ridgeline 2P Tent",
      "subtitle": "TENT-RIDGE-2P",
      "excerpt": "A two-person, three-season backpacking tent.",
      "score": 0.82,
      "updatedAt": "2026-10-16T09:30:00.000Z",
      "groupKey": "string"
    }
  ],
  "counts": {},
  "searched": [
    "PRODUCT"
  ]
}