Augeo AI Docs
AI Server

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.

EventWhen to send itWhat it tells us
item.viewedAn offer or reward shows on screen.What the member saw, and where in the list.
item.detail.viewedThe member opens the detail page.Which offers earned a closer look.
item.activatedThe member clicks or activates an offer.Which offers drew action.
search.performedThe member runs a search.What they looked for, and whether they found it.
cart.item.addedThe member adds an item to a cart.Intent to buy before checkout.
redemption.completedThe 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
  1. You send a batch. Post 1 to 50 flat events in one call.
  2. Augeo checks the caller. Your token decides which member owns each event.
  3. Augeo builds the full event. The server wraps each event in the augeo.event format.
  4. The SDK checks each event. It uses the same registry as our own apps.
  5. Bad events fail alone. Good events in the same batch still go through.
  6. Good events reach the event lake. Delivery is best-effort. A 202 is not a storage receipt.
  7. 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.

ReportWhat it shows
List eventsCounts, members, and last seen time for each event name.
Event trendDaily counts for one event.
FunnelThe order in which members move through events.
Compare cohortsHow members who did one thing differ from the rest.
Test resultsHow 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_id for each member. Reports count each member once.
  • The app name. application becomes the host. Reports can split by host.
  • The time. time is 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_events

Try 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:create

A 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_reported

Analytics 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 redemption

ui, 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
      }
    }
  ]
}

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 Unavailable

A 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"
      }
    ]
  }
}

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.