HTTP ingestion
Use this contract when building a custom native, Flutter, React Native or web adapter. Downloadable Swift, JavaScript / React Native, Kotlin and Dart source adapters implement it. There are no published npm, Maven or pub.dev packages at this time.
Endpoint and authentication
POST https://api.submetry.com/v1/events Content-Type: application/json Authorization: Bearer YOUR_PUBLIC_KEY
Use the app's sub_pk_ ingestion key from Setup. It can submit events for that app and cannot read analytics or administer apps. Private server keys and webhook secrets serve different purposes.
Payload
{
"app_id": "YOUR_APP_ID",
"events": [
{
"id": "evt_UNIQUE_ID",
"ts": 1791288000,
"name": "onboarding_completed",
"sid": "sess_CURRENT_SESSION_ID",
"aid": "anon_PERSISTED_INSTALLATION_ID",
"uid": "OPTIONAL_REVENUECAT_OR_APP_USER_ID",
"props": {},
"context": {
"platform": "ios",
"app_version": "1.0.0",
"build": "1",
"environment": "debug",
"locale": "en_CA",
"timezone": "America/Toronto"
}
}
]
}The timestamp above illustrates the format; generate the current Unix timestamp in seconds at the moment the event occurs. Omit uid while there is no known identity. app_id, if supplied, must match the key's app.
| Field | Requirement |
|---|---|
events | 1–100 events; total request body at most 256 KiB |
id, sid, aid | Nonempty strings, at most 128 characters |
uid | Optional nonempty string, at most 128 characters; omit rather than send null |
ts | Finite Unix seconds, within the last 30 days and no more than five minutes ahead |
name | Lowercase snake_case, initial letter, at most 80 characters; no rc_ prefix |
props | JSON object, at most 8 KiB |
context | Optional JSON object; each value a string of at most 256 characters |
context.environment | production, debug, sandbox or testflight |
Quick development request
This sends one real development event. It creates a integration_verified entry in the selected app; it does not verify your application code.
curl https://api.submetry.com/v1/events \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SUBMETRY_PUBLIC_KEY" \
--data "{\"app_id\":\"$SUBMETRY_APP_ID\",\"events\":[{\"id\":\"evt_$(uuidgen)\",\"ts\":$(date +%s),\"name\":\"integration_verified\",\"sid\":\"setup_session\",\"aid\":\"setup_device\",\"props\":{},\"context\":{\"environment\":\"debug\"}}]}"Responses and retries
- 202: ingestion acknowledged; inspect the returned accepted/duplicate counts. Repeated event IDs are deduplicated within the app.
- 400/413: invalid payload or oversized body; correct or archive rejected events before replay.
- 401: wrong, revoked or rotated app key; correct configuration.
- 429: rate limited; back off. The ingestion limit is 120 batches per app per minute.
- 503/network failure: retain events and retry with exponential backoff.
Never generate new event IDs when retrying. Remove queued events only after acceptance; persist the queue before sending and cap batch size. Cloudflare aggregates update on a ten-minute schedule; 202 is not a guarantee that a chart has already refreshed.
Adapter behavior
Persist a random anonymous ID per installation, generate a new session ID at session entry, and record first_open once. Send session_start and app_open at launch/foreground. Use a disk-backed event queue; flush periodically, in bounded batches and before background suspension when feasible. Update uid after successful RevenueCat identity changes. Instrument the event vocabulary.
Native mobile HTTP requests are supported. A browser app should send through its own same-origin server route to this HTTPS endpoint: the API does not currently publish a cross-origin browser CORS contract. A public ingestion key may be used by that server adapter; never expose a private analytics key to browsers.