Events API
Tell Augeo what your members do in your app. Views, searches, cart adds, and redeems shape offers and reports.
Events API
Use this API to tell Augeo what your members do in your app. Each time a member sees an offer, opens it, searches, or redeems, you send a small event. Augeo uses those events to learn what each member cares about and to measure how your program performs.
You send a simple JSON batch to one endpoint. Augeo does the heavy lifting. You do not build CloudEvents or learn our internal schemas.
Every event name and its fields are in the event catalogue. The machine contract is the OpenAPI reference.
What we track
These are the six events you can send today. Each one answers a simple question about a member.
| Event | When to send it | What it tells us |
|---|---|---|
item.viewed | An offer or reward shows on screen. | What the member saw, and where in the list. |
item.detail.viewed | The member opens the detail page. | Which offers earned a closer look. |
item.activated | The member clicks or activates an offer. | Which offers drew action. |
search.performed | The member runs a search. | What they looked for, and whether they found it. |
cart.item.added | The member adds an item to a cart. | Intent to buy before checkout. |
redemption.completed | The member redeems. Server API keys only. | The outcome that matters most. |
Together these events form a member journey, from seeing an offer to redeeming it. Augeo uses that journey in two ways. First, it picks offers for each member. Views, clicks, and redeems show the models which offers fit each member. Second, it measures your program. The same events feed the reports your Augeo team reviews with you.
How it works
Your app or server
-> POST /api/send_events (Augeo AI Server checks the token and user)
-> Augeo events SDK (checks each event)
-> Augeo event stream (accepted events only)
-> Event lake
-> Analytics and model training- You send a batch. Post 1 to 50 flat events in one call.
- Augeo checks the caller. Your token decides which member owns each event.
- Augeo builds the full event. The server wraps each event in the
augeo.eventformat. - The SDK checks each event. It uses the same registry as our own apps.
- Bad events fail alone. Good events in the same batch still go through.
- Good events reach the event lake. Delivery is best-effort. A 202 is not a storage receipt.
- Analytics and models read the lake. Your events sit next to our own app events.
The server adds the event class, version, app name, and member reference for you. See Who the user is for how the token picks the member.
How it ties into analytics
Augeo analytics reads the same event lake. Once an event lands, analytics can query it like any other event. Partners do not call the analytics API. Your Augeo team runs these reports with you.
| Report | What it shows |
|---|---|
| List events | Counts, members, and last seen time for each event name. |
| Event trend | Daily counts for one event. |
| Funnel | The order in which members move through events. |
| Compare cohorts | How members who did one thing differ from the rest. |
| Test results | How each test variant did, per member. |
Use List events to confirm that your events arrive.
These fields matter most for reports:
- The member. Send a stable
user_idfor each member. Reports count each member once. - The app name.
applicationbecomes the host. Reports can split by host. - The time.
timeis when the event happened. Funnels and trends sort by it. - Partner redeems. The server stamps these
measurementOrigin = partner_reported. Reports can tell them apart from store confirmations.
Where to send
Every environment uses the same path.
POST /api/send_events
Development https://ai-server.dev.augeoai.net/api/send_events
Staging https://ai-server.stage.augeoai.net/api/send_events
Production https://api.augeoai.net/api/send_eventsTry one call
Mint a new id for each event. Set time to the current UTC time. The server rejects a stale sample time after seven days.
TIME="$(date -u +%Y-%m-%dT%H:%M:%S.000Z)"
curl -sS -X POST "https://api.augeoai.net/api/send_events" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d "{
\"application\": \"rewardshub\",
\"client\": \"encore-values\",
\"user_id\": \"member-88231\",
\"events\": [
{
\"id\": \"3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61\",
\"type\": \"item.viewed\",
\"time\": \"${TIME}\",
\"data\": {
\"item\": { \"kind\": \"reward\", \"id\": \"offer-1842\" },
\"listId\": \"featured\",
\"position\": 2,
\"exposureMs\": 1200
}
}
]
}"Swap in your token. Swap in a new event id. When every event passes, the call returns 202 and a results array. Delivery is best-effort. A 202 does not promise durable storage.
How to sign in
Every call needs a bearer token. A missing, bad, or expired token returns 401. The server keeps nothing from that call.
Authorization: Bearer <token>Member app Member session token Token identity. A different user id fails the call.
Server API key The user id you send. The key user is not a fallback.
Session or OAuth Better Auth or OAuth Token user. A different user id fails the call.A member session token starts with eus_.
OAuth callers need the same permission as the raw path.
agent:events:createA call with no Authorization header returns:
{
"error": "Unauthorized",
"message": "Authorization header with Bearer token is required"
}A bad API key, an expired OAuth token, or an unknown bearer returns error as a string:
{
"error": "Unauthorized",
"message": "Invalid or expired token"
}If the member session fails, the body has an error object. The recoverable flag is true. Get a fresh member session token and send the batch again.
{
"error": {
"code": "SESSION_EXPIRED",
"message": "End-user session has expired",
"recoverable": true
}
}The code is SESSION_INVALID, SESSION_EXPIRED, or SESSION_REVOKED.
A token that lacks permission returns 403:
{
"error": "Forbidden",
"message": "Insufficient scope"
}If sign-in storage is down, the call returns 503:
{
"error": "Service Unavailable",
"message": "Authentication temporarily unavailable"
}403 and 503 come from sign-in, not from event checks. The status list below applies after sign-in succeeds.
What to send
Send JSON. Set the content type to application/json.
application required Host slug. Exact match. Becomes host.applicationName.
client optional Label ^[a-z0-9]+(-[a-z0-9]+)*$, at most 64 characters.
Becomes clientName and the default source.instanceId.
A label, not a tenant.
environment optional Your own environment, such as uat.
Becomes host.environment. Does not pick the Augeo host.
user_id optional Default member id. See Who the user is.
events required 1 to 50 items.
events[].id required Unique string. A UUID is enough. Dedupe key.
events[].type required Short name or full name.
events[].time required ISO-8601 with a timezone, or epoch ms.
events[].data required Occurrence payload for that type.
events[].user_id optional Per-event member id. API key override.
events[].source optional Default surface partner_api.
instanceId is client, or else application.
events[].correlation optional Default {}.
events[].typeversion optional Default is the registry version for type.Leave source out to use the default.
If you send source, the server checks that object as sent.
The server does not fill a missing field on a source you sent.
Leave correlation out to send an empty object.
A typeversion you send must match the registry version.
The server does not swap in a different version.
The server sets spec, specversion, class, and a missing typeversion from the registry.
Who the user is
A member token names the user.
A Better Auth session uses that session user.
An OAuth token uses the signed-in user.
If a body user id differs from that id, the whole call is 400.
The code is user_mismatch.
Leave user id out when the token already names the member.
An API key does not fall back to the key service user. Each event needs a user id, on that event or at the top. A per-event value wins, even when that value fails the check. A missing value fails that event with required.
participantRef = <application>:<user_id>The client label is not part of that reference.
A partner member id must match this pattern:
^[A-Za-z0-9._:-]{1,128}$The server rejects a value that contains @. Do not send an email address.
Only an API key may send that redemption event.
Any other credential gets forbidden_for_credential for that event.
The server marks that redemption as partner reported.
measurementOrigin = partner_reportedAnalytics uses that stamp to tell a partner report from a storefront confirmation. You do not need a ledger reference.
Only a member session can set the trusted organization. Client, environment, and user id do not grant an organization.
Which app name
The application value must be an exact slug.
This path takes the host list except factory.
Today that list is theo, rewardshub, and kigo.
The server rejects factory here.
The server does not trim the value or change its case.
A rejection names the value you sent and lists the names it takes:
{
"error": "invalid_request",
"errors": [
{
"path": "/application",
"code": "not_registered",
"message": "Offered \"partner-embed\"; accepted values: [\"theo\",\"rewardshub\",\"kigo\"]"
}
]
}A missing value shows as <missing>.
Read the accepted list in the message.
Do not assume the list never grows.
Which event names
Only names in profile augeo.partner-ingest@1 may pass.
Send the short name or the full name.
Both map to the registered name.
The server returns not_allowed for a known name outside the profile.
The server returns unknown_type for an unknown name.
item.viewed com.augeo.engagement.item.viewed impression
item.detail.viewed com.augeo.engagement.item.detail.viewed detail view
item.activated com.augeo.engagement.item.activated activation
search.performed com.augeo.engagement.search.performed search
cart.item.added com.augeo.engagement.cart.item.added add to cart
redemption.completed com.augeo.engagement.redemption.completed partner-reported redemptionui, conversation, and factory names are out of v1.
Size and time
Send at least one event and at most 50. Time as text must include a timezone. An integer epoch in ms may also pass. The server rejects a numeric string. The time cannot be more than five minutes ahead. The time cannot be older than seven days. Both bounds include the edge. The server stores the time as epoch ms.
A search keyword must be 1 to 200 characters.
When you did not filter, omit categoryId and productType.
Page must be 1 or greater.
When outcome is success, resultCount must be 1 or greater.
When outcome is empty, resultCount must be 0.
Sample calls
Each block below is one full valid request. These times do not move. A live call must use a current time, as in the first sample.
Item view
item.viewed is an impression. This event is not a click and not a detail view.
{
"application": "rewardshub",
"client": "encore-values",
"environment": "uat",
"user_id": "member-88231",
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
}
]
}Detail view
item.detail.viewed means the member opened the item. A card that scrolled past is an impression, not this event.
{
"application": "rewardshub",
"client": "encore-values",
"environment": "uat",
"user_id": "member-88231",
"events": [
{
"id": "4b8e1d22-7c31-4a90-9f28-1d6c9b3e5a70",
"type": "item.detail.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"entryPoint": "card-activation",
"listId": "featured",
"position": 2
}
}
]
}Item click
item.activated means the member acted on an item. This event is not a committed redemption.
{
"application": "rewardshub",
"client": "encore-values",
"environment": "uat",
"user_id": "member-88231",
"events": [
{
"id": "5c9f2e33-8d42-4b01-a039-2e7d0c4f6b81",
"type": "item.activated",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"activation": "open",
"listId": "featured",
"position": 2
}
}
]
}A search
search.performed records a search and the results state you showed.
{
"application": "rewardshub",
"client": "encore-values",
"environment": "uat",
"user_id": "member-88231",
"events": [
{
"id": "7c1e4b90-2a55-4f63-8d01-9e6a3c5b7d82",
"type": "search.performed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"keyword": "coffee",
"outcome": "success",
"page": 1,
"resultCount": 24
}
}
]
}A search with no hits uses outcome empty and resultCount 0.
Cart add
{
"application": "rewardshub",
"client": "encore-values",
"environment": "uat",
"user_id": "member-88231",
"events": [
{
"id": "6d0a3f44-9e53-4c12-b14a-3f8e1d5a7c92",
"type": "cart.item.added",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842",
"quantity": 1
},
"listId": "featured",
"position": 2
}
}
]
}A redeem
Send this only from your server, with an API key, after the redemption has committed. Do not send this from a browser click.
{
"application": "rewardshub",
"client": "encore-values",
"environment": "uat",
"user_id": "member-88231",
"events": [
{
"id": "a81d0e47-5c92-4b16-a3f8-2d7e9b0c4a15",
"type": "com.augeo.engagement.redemption.completed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"items": [
{
"kind": "reward",
"id": "offer-1842",
"quantity": 1
}
],
"redemptionKind": "points",
"valueBand": "1000-4999"
},
"user_id": "member-99102"
}
]
}The batch
{
"application": "rewardshub",
"client": "encore-values",
"environment": "uat",
"user_id": "member-88231",
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "4b8e1d22-7c31-4a90-9f28-1d6c9b3e5a70",
"type": "item.detail.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"entryPoint": "card-activation",
"listId": "featured",
"position": 2
}
},
{
"id": "5c9f2e33-8d42-4b01-a039-2e7d0c4f6b81",
"type": "item.activated",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"activation": "open",
"listId": "featured",
"position": 2
}
},
{
"id": "7c1e4b90-2a55-4f63-8d01-9e6a3c5b7d82",
"type": "search.performed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"keyword": "coffee",
"outcome": "success",
"page": 1,
"resultCount": 24
}
},
{
"id": "6d0a3f44-9e53-4c12-b14a-3f8e1d5a7c92",
"type": "cart.item.added",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842",
"quantity": 1
},
"listId": "featured",
"position": 2
}
},
{
"id": "a81d0e47-5c92-4b16-a3f8-2d7e9b0c4a15",
"type": "com.augeo.engagement.redemption.completed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"items": [
{
"kind": "reward",
"id": "offer-1842",
"quantity": 1
}
],
"redemptionKind": "points",
"valueBand": "1000-4999"
},
"user_id": "member-99102"
}
]
}What comes back
202 Every event passed. accepted, rejected 0, results
207 Some passed, some not. accepted, rejected, results
400 Every event failed. error invalid_events, accepted 0, rejected, results
400 Bad request. error invalid_request, errors
401 Missing or bad token. See How to sign in.
403 Missing permission. error Forbidden
503 Sign-in store down. error Service UnavailableA bad request includes bad JSON or a bad client. It also includes a missing or unknown application. It also includes zero events, more than 50 events, a duplicate id, or a user mismatch. The server sends nothing from that call.
Each results entry has index, id, type, and status.
Status is accepted or rejected.
A failed entry also has errors.
Each error has path, code, and message.
Id is the string you sent, or null when that field was absent or not a string.
Type is the full registered name, the string you sent, or null.
Paths are JSON pointers into your request. A schema path under data.occurrence is rewritten to data. Match on path and code. Do not depend on the prose in message.
All pass
{
"accepted": 6,
"rejected": 0,
"results": [
{
"index": 0,
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "com.augeo.engagement.item.viewed",
"status": "accepted"
},
{
"index": 1,
"id": "4b8e1d22-7c31-4a90-9f28-1d6c9b3e5a70",
"type": "com.augeo.engagement.item.detail.viewed",
"status": "accepted"
},
{
"index": 2,
"id": "5c9f2e33-8d42-4b01-a039-2e7d0c4f6b81",
"type": "com.augeo.engagement.item.activated",
"status": "accepted"
},
{
"index": 3,
"id": "7c1e4b90-2a55-4f63-8d01-9e6a3c5b7d82",
"type": "com.augeo.engagement.search.performed",
"status": "accepted"
},
{
"index": 4,
"id": "6d0a3f44-9e53-4c12-b14a-3f8e1d5a7c92",
"type": "com.augeo.engagement.cart.item.added",
"status": "accepted"
},
{
"index": 5,
"id": "a81d0e47-5c92-4b16-a3f8-2d7e9b0c4a15",
"type": "com.augeo.engagement.redemption.completed",
"status": "accepted"
}
]
}Some fail
The second event claims success and a zero result count. The other events still pass.
{
"accepted": 2,
"rejected": 1,
"results": [
{
"index": 0,
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "com.augeo.engagement.item.viewed",
"status": "accepted"
},
{
"index": 1,
"id": "7c1e4b90-2a55-4f63-8d01-9e6a3c5b7d82",
"type": "com.augeo.engagement.search.performed",
"status": "rejected",
"errors": [
{
"path": "/events/1/data/resultCount",
"code": "too_small",
"message": "resultCount must be >= 1 when outcome is \"success\""
}
]
},
{
"index": 2,
"id": "a81d0e47-5c92-4b16-a3f8-2d7e9b0c4a15",
"type": "com.augeo.engagement.redemption.completed",
"status": "accepted"
}
]
}All fail
{
"error": "invalid_events",
"accepted": 0,
"rejected": 1,
"results": [
{
"index": 0,
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "com.augeo.engagement.item.viewed",
"status": "rejected",
"errors": [
{
"path": "/events/0/data/item/id",
"code": "required",
"message": "item.id is required"
}
]
}
]
}Error names
required A needed field is missing.
invalid_type The value has the wrong type.
invalid_value The value is not acceptable.
too_small The value is too low.
too_big The value is too high.
unknown_type The type is not in the registry.
not_allowed The type is known, but not in the partner profile.
forbidden_for_credential This credential cannot send that type.
not_registered The application is not on the partner list.
duplicate_id The id repeats an earlier event in this batch.
user_mismatch The user id does not match the token.After the request shape is valid, the server checks each event in order. First the server must know the type. Then the type must be in the profile. Then the credential must allow that type. Then the envelope and payload must pass. Then the app name must pass. User id rules are last.
The server drops unknown keys in data. The server strips email, name, and other private keys at any depth. Do not send those values and expect the server to keep them.
Known bad calls
Each block records the status, error kind, path, and code for one defect.
The request field is the body that produces that result.
rawBody is the raw text when the body is not JSON.
These blocks are the contract samples.
The response shapes for a full pass, a partial batch, and a full fail are above.
Bad JSON
{
"status": 400,
"error": "invalid_request",
"path": "/",
"code": "invalid_value",
"rawBody": "{"
}No events
{
"status": 400,
"error": "invalid_request",
"path": "/events",
"code": "required",
"request": {
"application": "rewardshub"
}
}Empty list
{
"status": 400,
"error": "invalid_request",
"path": "/events",
"code": "too_small",
"request": {
"application": "rewardshub",
"events": []
}
}Too many
{
"status": 400,
"error": "invalid_request",
"path": "/events",
"code": "too_big",
"request": {
"application": "rewardshub",
"events": [
{
"id": "00000000-0000-4000-8000-000000000000",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000001",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000002",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000003",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000004",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000005",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000006",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000007",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000008",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000009",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000000a",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000000b",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000000c",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000000d",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000000e",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000000f",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000010",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000011",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000012",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000013",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000014",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000015",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000016",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000017",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000018",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000019",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000001a",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000001b",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000001c",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000001d",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000001e",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000001f",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000020",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000021",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000022",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000023",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000024",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000025",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000026",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000027",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000028",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000029",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000002a",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000002b",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000002c",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000002d",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000002e",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-00000000002f",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000030",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000031",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "00000000-0000-4000-8000-000000000032",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
}
]
}
}No app
{
"status": 400,
"error": "invalid_request",
"path": "/application",
"code": "required",
"request": {
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
}
]
}
}Factory name
{
"status": 400,
"error": "invalid_request",
"path": "/application",
"code": "not_registered",
"request": {
"application": "factory",
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
}
]
}
}Same id
{
"status": 400,
"error": "invalid_request",
"path": "/events/1/id",
"code": "duplicate_id",
"request": {
"application": "rewardshub",
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "search.performed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"keyword": "coffee",
"outcome": "success",
"page": 1,
"resultCount": 24
}
}
]
}
}Wrong user
{
"status": 400,
"error": "invalid_request",
"path": "/user_id",
"code": "user_mismatch",
"request": {
"application": "rewardshub",
"user_id": "member-other",
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
}
]
}
}Event user
{
"status": 400,
"error": "invalid_request",
"path": "/events/0/user_id",
"code": "user_mismatch",
"request": {
"application": "rewardshub",
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
},
"user_id": "member-other"
}
]
}
}No item id
{
"status": 400,
"error": "invalid_events",
"path": "/events/0/data/item/id",
"code": "required",
"request": {
"application": "rewardshub",
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward"
}
}
}
]
}
}Bad type
{
"status": 400,
"error": "invalid_events",
"path": "/events/0/type",
"code": "unknown_type",
"request": {
"application": "rewardshub",
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "not.a.real.event",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
}
]
}
}Not on list
{
"status": 400,
"error": "invalid_events",
"path": "/events/0/type",
"code": "not_allowed",
"request": {
"application": "rewardshub",
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "com.augeo.ui.component.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
}
]
}
}Member redeem
{
"status": 400,
"error": "invalid_events",
"path": "/events/0/type",
"code": "forbidden_for_credential",
"request": {
"application": "rewardshub",
"events": [
{
"id": "a81d0e47-5c92-4b16-a3f8-2d7e9b0c4a15",
"type": "com.augeo.engagement.redemption.completed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"items": [
{
"kind": "reward",
"id": "offer-1842",
"quantity": 1
}
],
"redemptionKind": "points",
"valueBand": "1000-4999"
},
"user_id": "member-99102"
}
]
}
}No user id
{
"status": 400,
"error": "invalid_events",
"path": "/events/0/user_id",
"code": "required",
"request": {
"application": "rewardshub",
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
}
]
}
}Email user
{
"status": 400,
"error": "invalid_events",
"path": "/events/0/user_id",
"code": "invalid_value",
"request": {
"application": "rewardshub",
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
},
"user_id": "member@example.com"
}
]
}
}Bad search
The response for this request is the partial sample above. This block has the path and code.
{
"status": 207,
"error": "invalid_events",
"path": "/events/1/data/resultCount",
"code": "too_small",
"message": "resultCount must be >= 1 when outcome is \"success\"",
"request": {
"application": "rewardshub",
"user_id": "member-88231",
"events": [
{
"id": "3f2a9c1e-6b40-4d8a-9e17-0c5b8a2d4f61",
"type": "item.viewed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"item": {
"kind": "reward",
"id": "offer-1842"
},
"listId": "featured",
"position": 2,
"exposureMs": 1200
}
},
{
"id": "7c1e4b90-2a55-4f63-8d01-9e6a3c5b7d82",
"type": "search.performed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"keyword": "coffee",
"outcome": "success",
"page": 1,
"resultCount": 0
}
},
{
"id": "a81d0e47-5c92-4b16-a3f8-2d7e9b0c4a15",
"type": "com.augeo.engagement.redemption.completed",
"time": "2026-11-17T15:04:00.000Z",
"data": {
"items": [
{
"kind": "reward",
"id": "offer-1842",
"quantity": 1
}
],
"redemptionKind": "points",
"valueBand": "1000-4999"
},
"user_id": "member-99102"
}
]
}
}Try again
The server does not wait for downstream delivery. A delivery failure does not come back as an error. A 202, and a passed index on a 207, do not promise durable storage.
Send again only the failed indexes. Do not send a passed event again only because another index failed. The event id is the downstream dedupe key. This API does not keep a seen-id cache. Two later calls may both take the same id.