# HTTP ingestion

Use this contract when building a custom native, Flutter, React Native or web adapter. Downloadable [Swift](https://submetry.com/docs/swift.md), [JavaScript / React Native](https://submetry.com/docs/react-native.md), [Kotlin](https://submetry.com/docs/android.md) and [Dart](https://submetry.com/docs/flutter.md) source adapters implement it. There are no published npm, Maven or pub.dev packages at this time.

## Endpoint and authentication

```text
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

```json
{
  "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.

```bash
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](https://submetry.com/docs/events.md).

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.
