Augeo AI Server API
Public API for agent chat, conversation threads, suggested prompts, catalog search suggestions, agent events, the search widget, and Model Context Protocol (MCP) clients.
/api/agent-eventsInternal and deprecated. Used only by Augeo SDKs and widgets. Partners use POST /api/send_events. Requires a bearer token. Accepts a batch of 1–50 events in one form (compact augeo.event, CloudEvents 1.0, or widget envelope), or a standalone compact event or CloudEvent. Returns an empty 200 when every event is admitted. Each entry is validated independently: 207 when some entries are admitted and some are rejected, 400 with indexed errors when every entry is rejected. A malformed wrapper, an empty or oversized batch, or mixed event kinds returns 400 without indexed errors. A missing or unregistered data.context.host.applicationName is rejected per event after envelope validation. Admitted events are delivered best-effort and are not a durable acknowledgement.
Authorization
bearerAuth In: header
A batch of 1–50 events, a standalone compact augeo.event, or a standalone CloudEvents 1.0 event. Individual entries are admitted or rejected after the wrapper is accepted.
TypeScript Definitions
Use the request body type in TypeScript.
A batch of 1–50 events, a standalone compact augeo.event, or a standalone CloudEvents 1.0 event. Individual entries are admitted or rejected after the wrapper is accepted.
Batch of 1–50 events. Each entry is validated independently after the wrapper is accepted.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/api/agent-events" \ -H "Content-Type: application/json" \ -d '{ "events": [ null ] }'{ "accepted": 0, "errors": [ { "error": "Invalid events", "index": 0, "message": "string", "status": 400, "type": "string" } ], "rejected": 0}{ "accepted": 0, "error": "string", "errors": [ { "error": "Invalid events", "index": 0, "message": "string", "status": 400, "type": "string" } ], "message": "string", "rejected": 0}{ "error": "string", "message": "string"}curl -X POST "https://example.com/api/agent/chat"/api/catalog/search/suggestionsSuggested search actions for the authenticated member. The provider comes from the authenticated session. A Rewards Hub session requests datasets: ["popularSearches"], limit: 5. Plain rows are catalog completions from those popular terms; framed rows are assistant prompts for the client to seed, not prompts this endpoint runs. Debounce typing by approximately 250 ms before calling. Omit q, or send it blank, for the on-focus list of unfiltered popular terms. Displayed search rows are the first three distinct nonblank popular terms, lowercased, in upstream order. Decorated assistant chips are curated phrases looked up from every nonblank popular term, not template text filled from those bases. Up to three phrases are picked at random from the whole matched pool, with repeated phrase text dropped, and fill the decorated chips in popularity, personalization, budget order before one recommendation prompt. One or two matched phrases yield one or two chips. No matched phrase omits the decorated chips entirely, and the old template strings are not used to pad the list. Previously, any nonempty popular list always emitted three decorated template prompts. Zero usable popular terms yield only the recommendation prompt. Every term is lowercase, for example "fresh roasted coffee" and "what should i redeem next?". A Kigo session never calls that read. It requests merchant typeahead, returns at most three distinct nonblank merchant names as ordinary search rows, and does not add assistant prompts. A trimmed Kigo query outside 2–100 characters returns no suggestions and makes no upstream request. Kigo may also send a complete location and catalog_filter_ids; other filters are rejected.
Authorization
bearerAuth In: header
Query Parameters
Partial search text. Rewards Hub trims and caps at 256 characters. A Kigo session uses the trimmed text only when it is 2–100 characters and does not truncate a longer query.
Kigo location latitude. Sent only with longitude, radius, and search_radius_unit.
Comma-separated catalog filter UUIDs forwarded to Kigo typeahead.
Response Body
application/json
application/json
curl -X GET "https://example.com/api/catalog/search/suggestions"{ "suggestions": [ { "query": { "keyword": "coffee" }, "source": "suggested_search", "term": "coffee", "type": "search" }, { "query": { "keyword": "nike shoes" }, "source": "suggested_search", "term": "nike shoes", "type": "search" }, { "query": { "keyword": "sunglasses" }, "source": "suggested_search", "term": "sunglasses", "type": "search" }, { "base_term": "coffee", "source": "popularity", "term": "fresh roasted coffee", "type": "ai_prompt" }, { "base_term": "nike shoes", "source": "personalization", "term": "running shoes for weekend miles", "type": "ai_prompt" }, { "base_term": "sunglasses", "source": "budget", "term": "polarized shades for sunny days", "type": "ai_prompt" }, { "source": "recommendation", "term": "what should i redeem next?", "type": "ai_prompt" } ]}{ "error": "string", "message": "string"}curl -X POST "https://example.com/api/offers/wallet/actions"curl -X POST "https://example.com/api/offers/wallet/state"/api/pdp/promptsAuthorization
bearerAuth In: header
Query Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/pdp/prompts?productId=string"{ "outcome": "ready", "policyVersion": "string", "product": { "productId": 1 }, "promptSetId": "string", "prompts": [ { "id": "generated-1", "kind": "generated", "label": "string", "provenance": "catalog_generation", "question": "string" }, { "id": "generated-1", "kind": "generated", "label": "string", "provenance": "catalog_generation", "question": "string" }, { "id": "generated-1", "kind": "generated", "label": "string", "provenance": "catalog_generation", "question": "string" } ], "schemaVersion": 1}{ "error": "Invalid request", "message": "The product reference is invalid.", "outcome": "invalid_request"}{ "error": { "code": "SESSION_INVALID", "message": "string", "recoverable": true }}{ "error": "Forbidden", "message": "Insufficient scope"}{ "error": "Not found", "message": "This product is not available.", "outcome": "unavailable", "reason": "product"}{ "error": "Unavailable", "message": "Product questions are temporarily unavailable.", "outcome": "unavailable", "reason": "session"}curl -X GET "https://example.com/api/prompts/suggested"/api/search-sdk/catalogAuthorization
bearerAuth In: header
Query Parameters
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/api/search-sdk/catalog"{ "has_more": true, "products": [ { "action": "cart.add", "badge": "string", "brand": "string", "cta": "add_to_cart", "denomination_count": -9007199254740991, "has_variants": true, "image_url": "string", "in_wishlist": true, "max_points_price": 0, "min_points_price": 0, "name": "string", "points_price": 0, "product_id": -9007199254740991, "product_type": "standalone", "reason": "string", "requires_selection": true, "split_tender": { "cash_amount": { "amount": 0, "currency": "string" }, "status": "potentially_eligible" }, "wishlist_enabled": true } ], "total_pages": -9007199254740991}{ "error": "string", "message": "string"}{ "error": "string", "message": "string"}/api/search-sdk/recently-viewedAuthorization
bearerAuth In: header
Query Parameters
Page size, 1-25, default 10. Unparseable values use the default; out-of-range values clamp.
1-based page, default 1, at most 100. Unparseable values use the default; out-of-range values clamp.
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/api/search-sdk/recently-viewed"{ "error": "string", "limit": -9007199254740991, "page": -9007199254740991, "products": [ { "action": "cart.add", "badge": "string", "brand": "string", "cta": "add_to_cart", "denomination_count": -9007199254740991, "has_variants": true, "image_url": "string", "in_wishlist": true, "max_points_price": 0, "min_points_price": 0, "name": "string", "points_price": 0, "product_id": -9007199254740991, "product_type": "standalone", "reason": "string", "requires_selection": true, "split_tender": { "cash_amount": { "amount": 0, "currency": "string" }, "status": "potentially_eligible" }, "wishlist_enabled": true } ], "unavailable": true}{ "error": "string", "message": "string"}{ "error": "string", "message": "string"}/api/search-sdk/recentsAuthorization
bearerAuth In: header
Query Parameters
Page size, 1-25, default 10. Unparseable values use the default; out-of-range values clamp.
1-based page, default 1, at most 100. Unparseable values use the default; out-of-range values clamp.
Newest first (recent) or most searched first (frequent). Any other value is ignored and the upstream default applies.
Only searches from the last N days. A value that is not a positive integer is ignored.
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/api/search-sdk/recents"{ "error": "string", "has_more": true, "items": [ { "count": 0, "id": "string", "last_searched_date": "string", "search_text": "string" } ], "page": -9007199254740991, "page_size": -9007199254740991, "total_count": -9007199254740991, "unavailable": true}{ "error": "string", "message": "string"}{ "error": "string", "message": "string"}/api/search-sdk/recentsAuthorization
bearerAuth In: header
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/api/search-sdk/recents" \ -H "Content-Type: application/json" \ -d '{ "query": "string", "submission_id": "string" }'{ "recorded": true}{ "error": "string", "message": "string"}{ "error": "string", "message": "string"}/api/search-sdk/recents/{id}Authorization
bearerAuth In: header
Path Parameters
Response Body
application/json
application/json
application/json
curl -X DELETE "https://example.com/api/search-sdk/recents/string"{ "dismissed": true}{ "error": "string", "message": "string"}{ "error": "string", "message": "string"}/api/search-sdk/suggestionsAuthorization
bearerAuth In: header
Query Parameters
Cap on popular terms used to assemble suggestions, at most 20. Predictive recents return no more than the requested limit or three entries, whichever is smaller.
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/api/search-sdk/suggestions"{ "recents": { "error": "string", "items": [ { "count": 0, "id": "string", "last_searched_date": "string", "search_text": "string" } ], "unavailable": true }, "suggestions": { "error": "string", "items": [ { "query": { "keyword": "string" }, "source": "suggested_search", "term": "string", "type": "search" } ], "unavailable": true }}{ "error": "string", "message": "string"}{ "error": "string", "message": "string"}/api/send_eventsRequires the same bearer credential as agent events. Partners send a batch of 1–50 flat events. The server builds the compact augeo.event, validates it with the events SDK, and delivers admitted events best-effort to the existing events sink. All admitted events return 202 with results. A mix returns 207. A well-formed batch whose events are all rejected returns 400 invalid_events. A malformed wrapper, unregistered application, duplicate id, or session user mismatch returns 400 invalid_request and delivers nothing. redemption.completed is accepted only from an API key and is stamped partner_reported. Cross-request dedupe stays downstream on event id.
Authorization
bearerAuth In: header
Partner batch. The runtime accepts the wrapper and admits each event independently. This schema documents the contract, including SDK occurrence variants discriminated by type. Unknown wrapper keys are ignored.
TypeScript Definitions
Use the request body type in TypeScript.
Partner batch. The runtime accepts the wrapper and admits each event independently. This schema documents the contract, including SDK occurrence variants discriminated by type. Unknown wrapper keys are ignored.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/send_events" \ -H "Content-Type: application/json" \ -d '{ "application": "rewardshub", "client": "encore-values", "environment": "uat", "events": [ { "data": { "exposureMs": 1200, "item": { "id": "offer-1842", "kind": "reward" }, "listId": "featured", "position": 2 }, "id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61", "time": "2026-11-17T15:04:00.000Z", "type": "item.viewed" } ], "user_id": "member-88231" }'{ "accepted": 6, "rejected": 0, "results": [ { "id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61", "index": 0, "status": "accepted", "type": "com.augeo.engagement.item.viewed" }, { "id": "4b8e1d22-7c31-4a90-9f28-1d6c9b3e5a70", "index": 1, "status": "accepted", "type": "com.augeo.engagement.item.detail.viewed" }, { "id": "5c9f2e33-8d42-4b01-a039-2e7d0c4f6b81", "index": 2, "status": "accepted", "type": "com.augeo.engagement.item.activated" }, { "id": "7c1e4b90-2a55-4f63-8d01-9e6a3c5b7d82", "index": 3, "status": "accepted", "type": "com.augeo.engagement.search.performed" }, { "id": "6d0a3f44-9e53-4c12-b14a-3f8e1d5a7c92", "index": 4, "status": "accepted", "type": "com.augeo.engagement.cart.item.added" }, { "id": "a81d0e47-5c92-4b16-a3f8-2d7e9b0c4a15", "index": 5, "status": "accepted", "type": "com.augeo.engagement.redemption.completed" } ]}{ "accepted": 2, "rejected": 1, "results": [ { "id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61", "index": 0, "status": "accepted", "type": "com.augeo.engagement.item.viewed" }, { "errors": [ { "code": "too_small", "message": "resultCount must be >= 1 when outcome is \"success\"", "path": "/events/1/data/resultCount" } ], "id": "7c1e4b90-2a55-4f63-8d01-9e6a3c5b7d82", "index": 1, "status": "rejected", "type": "com.augeo.engagement.search.performed" }, { "id": "a81d0e47-5c92-4b16-a3f8-2d7e9b0c4a15", "index": 2, "status": "accepted", "type": "com.augeo.engagement.redemption.completed" } ]}{ "error": "invalid_request", "errors": [ { "code": "not_registered", "message": "Offered \"partner-embed\"; accepted values: [\"theo\",\"rewardshub\",\"kigo\"]", "path": "/application" } ]}{ "error": "string", "message": "string"}curl -X GET "https://example.com/api/threads"curl -X POST "https://example.com/api/threads"/api/threads/{threadId}Authorization
bearerAuth In: header
Path Parameters
curl -X GET "https://example.com/api/threads/string"/api/threads/{threadId}Authorization
bearerAuth In: header
Path Parameters
curl -X DELETE "https://example.com/api/threads/string"/api/threads/{threadId}Authorization
bearerAuth In: header
Path Parameters
curl -X PUT "https://example.com/api/threads/string"curl -X GET "https://example.com/mcp"curl -X POST "https://example.com/mcp"curl -X DELETE "https://example.com/mcp"curl -X GET "https://example.com/rewards-mcp"curl -X POST "https://example.com/rewards-mcp"curl -X DELETE "https://example.com/rewards-mcp"curl -X GET "https://example.com/rewards-mcp/server-card"