SubmetryDocumentationSet up your app →

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.

FieldRequirement
events1–100 events; total request body at most 256 KiB
id, sid, aidNonempty strings, at most 128 characters
uidOptional nonempty string, at most 128 characters; omit rather than send null
tsFinite Unix seconds, within the last 30 days and no more than five minutes ahead
nameLowercase snake_case, initial letter, at most 80 characters; no rc_ prefix
propsJSON object, at most 8 KiB
contextOptional JSON object; each value a string of at most 256 characters
context.environmentproduction, 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.