HTTP ingest API for other languages

The supported TypeScript SDK is the recommended integration for Web, Expo, and React Native. Other runtimes can send the same documented HTTP envelope while a native SDK is not yet available.

This is a transport contract, not a replacement for a production SDK. The caller owns consent, anonymous identity rotation, queueing, retry classification, payload limits, PII filtering, and shutdown delivery.

Endpoint

POST https://collector.analyticscli.com/v1/collect
Content-Type: application/json
X-API-Key: <publishable-project-key>

The publishable key determines the project. Do not send an admin or read-only query token. Use the canonical collector hostname shown above for every integration.

Envelope

{
  "sentAt": "2026-07-23T12:00:00.000Z",
  "events": [
    {
      "eventId": "11111111-1111-4111-8111-111111111111",
      "eventName": "project_created",
      "ts": "2026-07-23T12:00:00.000Z",
      "sessionId": "session-random-id",
      "anonId": "anonymous-random-id",
      "properties": {
        "plan": "free",
        "runtimeEnv": "production"
      },
      "platform": "server",
      "projectSurface": "api",
      "appVersion": "1.4.0",
      "type": "track"
    }
  ]
}

Use a UUID for every eventId and keep it unchanged when retrying the same event. This gives the ingest path an idempotency key. A batch contains at most 50 events and the complete request body must remain below 128 KiB.

Response handling

202: accepted for asynchronous processing;
400, 409, 413, other permanent 4xx: fix or drop the invalid payload;
408, 425, 429, 5xx, timeout, or network failure: retry with exponential backoff and jitter using the same event IDs.

Use a bounded queue and expose payload-free drop diagnostics. Do not retry a permanent validation error forever, because one poison event can otherwise block all healthy events behind it.

Privacy checklist

Do not send emails, names, phone numbers, addresses, IP addresses, tokens, secrets, receipts, or payment credentials.
Use runtimeEnv=production for Release traffic and a non-production value for Debug verification.
Keep platform and projectSurface separate.
Persist or link an identity only when the application’s consent and legal basis permit it.
Rotate identifiers when consent is withdrawn.
Prefer enums, booleans, bounded IDs, and numeric buckets over free text.

Verify

analyticscli --include-debug schema events --last 24h
analyticscli schema events --last 24h

The first command verifies test instrumentation. The second confirms real Release traffic. Do not treat a Debug event as production adoption.

Teams that need a maintained Swift, Kotlin, Flutter, Python, Go, or server SDK should share the runtime and delivery requirements before a native package is promoted as supported.