Event Ingestion

The event ingestion endpoint accepts batches of analytics events and queues them for processing.

Endpoint

POST https://api.adopture.com/api/v1/events

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`Idempotency-Key`	No	UUID for deduplication (300-second window)

Request Body

{
  "app_key": "ak_your_app_key_here",
  "sdk_version": "0.1.0",
  "events": [
    {
      "type": "track",
      "name": "button_clicked",
      "hashed_daily_id": "abc123...",
      "hashed_monthly_id": "def456...",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2025-01-15T10:30:00.000Z",
      "context": {
        "os": "iOS",
        "os_version": "17.2",
        "app_version": "1.0.0",
        "locale": "en_US",
        "device_type": "iPhone 15",
        "screen_width": 1179,
        "screen_height": 2556
      },
      "properties": {
        "button_name": "checkout"
      }
    }
  ]
}

Top-Level Fields

Field	Type	Required	Description
`app_key`	string	Yes	Your app key (starts with `ak_`)
`sdk_version`	string	No	SDK version sending the request
`events`	array	Yes	Array of event objects (max 100)

Event Object

Field	Type	Required	Description
`type`	string	Yes	`track`, `screen`, or `revenue`
`name`	string	Yes	Event name (1-200 characters)
`hashed_daily_id`	string	Yes	Daily rotating hash (16-128 characters)
`hashed_monthly_id`	string	Yes	Monthly rotating hash (16-128 characters)
`hashed_retention_id`	string	No	90-day retention hash (16-128 characters)
`session_id`	string	Yes	Session UUID (1-128 characters)
`timestamp`	string	Yes	ISO 8601 datetime (within 72h past to 1h future)
`context`	object	Yes	Device context (see below)
`properties`	object	No	Custom key-value pairs (max 50 keys, values max 500 characters)
`user_id`	string	No	User identifier (1-256 characters)
`revenue`	object	No	Revenue data (required when `type` is `revenue`)

Event Types

Type	Description
`track`	Custom event (button click, signup, etc.)
`screen`	Screen view
`revenue`	Purchase or subscription event

Context Object

The context object contains device and environment metadata:

Field	Type	Required	Description
`os`	string	Yes	Operating system (e.g., `iOS`, `Android`)
`os_version`	string	No	OS version (e.g., `17.2`)
`app_version`	string	No	Your app's version (e.g., `1.0.0`)
`locale`	string	No	Device locale (e.g., `en_US`)
`device_type`	string	No	Device model (e.g., `iPhone 15`)
`screen_width`	number	No	Screen width in pixels
`screen_height`	number	No	Screen height in pixels

Revenue Object

Required when the event type is revenue. See Revenue Events for the full field reference.

Constraints

Constraint	Limit
Max request body size	512 KB
Max events per request	100
Max properties per event	50 keys
Max property value length	500 characters
Timestamp range	72 hours in the past to 1 hour in the future

Response

Success (202 Accepted)

{
  "status": "accepted",
  "events": 1
}

The response indicates how many events were accepted for processing. A 202 status means the events have been queued — they will appear in your dashboard within seconds.

Rate Limit Headers

Every response includes rate limit information:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Include an Idempotency-Key header with a UUID to safely retry requests. The server remembers idempotency keys for 300 seconds. If a duplicate request is received within that window, the server returns the original response with an additional field:

{
  "status": "accepted",
  "events": 1,
  "deduplicated": true
}

For error responses and status codes, see Error Handling.

On this page