Augeo AI Docs
AI Server

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.

POST/api/agent-events

Internal 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
AuthorizationBearer <token>

In: header

Request Body

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    ]  }'
Empty
{  "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"}
POST/api/agent/chat

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X POST "https://example.com/api/agent/chat"
GET/api/catalog/search/suggestions

Suggested 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
AuthorizationBearer <token>

In: header

Query Parameters

q?string

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.

latitude?string

Kigo location latitude. Sent only with longitude, radius, and search_radius_unit.

longitude?string
radius?string
search_radius_unit?string
catalog_filter_ids?string

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"}
POST/api/offers/wallet/actions

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X POST "https://example.com/api/offers/wallet/actions"
POST/api/offers/wallet/state

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X POST "https://example.com/api/offers/wallet/state"
GET/api/pdp/prompts

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

productId*string

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"}
GET/api/prompts/suggested

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X GET "https://example.com/api/prompts/suggested"
GET/api/search-sdk/catalog

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

query?string
page?string
limit?string
latitude?string
longitude?string
radius?string
search_radius_unit?string
category_ids?string
catalog_filter_ids?string
merchant_ids?string
redemption_types?string
offer_types?string
single_offer_per_merchant?string
lightning_deal?string
trending?string
product_type?string
category_id?string

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"}
GET/api/search-sdk/recently-viewed

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

limit?number

Page size, 1-25, default 10. Unparseable values use the default; out-of-range values clamp.

page?number

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"}
GET/api/search-sdk/recents

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

limit?number

Page size, 1-25, default 10. Unparseable values use the default; out-of-range values clamp.

page?number

1-based page, default 1, at most 100. Unparseable values use the default; out-of-range values clamp.

sort?string

Newest first (recent) or most searched first (frequent). Any other value is ignored and the upstream default applies.

since_days?integer

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"}
POST/api/search-sdk/recents

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Request Body

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"}
DELETE/api/search-sdk/recents/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

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"}
GET/api/search-sdk/suggestions

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

limit?number

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"}
POST/api/send_events

Requires 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
AuthorizationBearer <token>

In: header

Request Body

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"}
GET/api/threads

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X GET "https://example.com/api/threads"
POST/api/threads

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X POST "https://example.com/api/threads"
GET/api/threads/{threadId}

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

threadId*string
curl -X GET "https://example.com/api/threads/string"
DELETE/api/threads/{threadId}

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

threadId*string
curl -X DELETE "https://example.com/api/threads/string"
PUT/api/threads/{threadId}

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

threadId*string
curl -X PUT "https://example.com/api/threads/string"
GET/mcp

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X GET "https://example.com/mcp"
POST/mcp

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X POST "https://example.com/mcp"
DELETE/mcp

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X DELETE "https://example.com/mcp"
GET/rewards-mcp

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X GET "https://example.com/rewards-mcp"
POST/rewards-mcp

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X POST "https://example.com/rewards-mcp"
DELETE/rewards-mcp

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X DELETE "https://example.com/rewards-mcp"
GET/rewards-mcp/server-card

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

curl -X GET "https://example.com/rewards-mcp/server-card"