Collector endpoint

The collector endpoint receives events from the Amperity Event Streams SDK and relays them to a real-time event stream. The SDK calls the collector for you. The SDK sends each event in its own request, as the event happens. Use this reference to understand the requests the SDK makes, to diagnose errors, or to test an event stream.

Request URL

Send requests to the collector URL with the path /api/collect/v1/{write-key}/events.

POST {collector-url}/api/collect/v1/{write-key}/events

The collector URL is shown as Endpoint on the event stream settings page. It is the same for every event stream on your Amperity stack. The write key in the path identifies the event stream.

Authentication

The collector endpoint does not use an API key or an access token. A valid write key in the request path is the only credential. Requests with a malformed, unknown, or deleted write key return 404 Not Found.

The collector accepts requests from any origin so that browsers can send events from your website.

Note

Amperity does not restrict write keys to specific website origins. Anyone who has a write key can send events to its event stream.

Requests

The request body is a JSON object that has an events array. The collector reads only the events array and ignores every other field. The Content-Type header may be application/json or text/plain. The SDK uses text/plain so that browsers do not send a preflight request. A Content-Length header is required.

The SDK sends one event in each request.

{
  "sentAt": "2026-10-26T12:00:00.000Z",
  "sdk": { "name": "@amperity/event-streams-browser", "version": "1.0.0" },
  "events": [
    {
      "type": "track",
      "event": "Order Completed",
      "eventId": "d1c0e0a4-6b3f-4f0e-9d2a-5f1c3b7a8e21",
      "anonymousId": "9f2e4c1a-7d3b-4a68-b0c5-2e8f1a6d9b34",
      "occurredAt": "2026-10-26T11:59:59.800Z",
      "properties": { "order_id": "A-1001", "total": 271.4 },
      "context": {}
    }
  ]
}

Limits

A request must meet the following requirements:

  • The body is a JSON object that has an events array of event objects.

  • The request body is no larger than 1 MiB.

  • Each event is no larger than 64 KiB when it reaches the real-time event stream, the same limit as the Real-time API.

Responses

The collector returns one status for each request.

Status

Meaning

202 Accepted

The collector forwarded every event, and none needs to be sent again. Review the results in the response body, because an event can be rejected.

400 Bad Request

The body is not valid JSON, or it does not have an events array of event objects.

404 Not Found

The write key is malformed, unknown, or deleted.

411 Length Required

The request does not have a Content-Length header.

413 Payload Too Large

The request body is larger than 1 MiB.

429 Too Many Requests

The Real-time API returned 429 for at least one event. Send the events again later.

503 Service Unavailable

At least one event got a 5xx status from the Real-time API or no response, or the collector could not forward events. Send the events again later.

A 202 Accepted response has a body that reports the result of each event:

{
  "results": [
    { "status": "accepted", "downstream_status": 202 }
  ]
}

The collector sends each event to the Real-time API and sets the status of the event from the status that the Real-time API returns. downstream_status is the status that the Real-time API returned, and it is not present when the Real-time API did not respond. Each event status is one of the following:

  • accepted: the Real-time API returned 202 or 204. A 202 means the event was accepted for processing. A 204 means the event stream is in Drop mode, so the event was accepted and then discarded.

  • retry: the Real-time API returned 429 or a 5xx status, or it did not respond within 5 seconds. The event was not delivered, and it can be sent again.

  • rejected: the Real-time API returned any other status, such as 409 when the event stream is in Reject mode, 404 when the event stream does not exist, 413 when the event is larger than 64 KiB, or 400 when the event is not a JSON object. The collector does not ask for the event to be sent again.

Note

It is safe to send a request again after some events in it are accepted. An event that is accepted again is not applied twice when its event type uses the event ID to deduplicate events.

How the collector forwards events

The collector forwards each event in a request to the event stream on its own, as soon as the request arrives, and it does not change the event. It does not add fields, hold events, batch events from different requests, or mark an event as coming from the SDK. The collector does not queue events. If an event is not delivered, the sender is responsible for sending it again, and the SDK does so.

Events that reach the event stream are processed in the same way as events that are sent to the Real-time API, including the event stream mode. The mode appears in the results: 204 for Drop and 409 for Reject.