SegOps AIDocs

Ingestion API

Ingest behavioral events from any server-side or client-side context. Events flow into the analytics warehouse where they power segment conditions in real time.

Single Event#

POST /api/ingestion/track/

bash
curl -X POST https://api.segops.ai/api/ingestion/track/ \
  -H "Authorization: ApiKey sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "event_type": "order_placed",
    "occurred_at": "2026-04-25T14:32:00Z",
    "payload": {
      "order_id": "ord-456",
      "total": 89.95,
      "currency": "USD"
    }
  }'

Response: 202 Accepted — { "queued": true }

FieldTypeRequiredDescription
user_idstringYesYour unique user identifier
event_typestringYesSnake-case event name, e.g. page_viewed
occurred_atstringNoISO 8601 timestamp. Defaults to receive time
payloadobjectNoArbitrary key→value properties

Batch Events (Recommended)#

POST /api/ingestion/track/batch/

Send up to 500 events in a single request. Preferred for server-side ingestors.

bash
curl -X POST https://api.segops.ai/api/ingestion/track/batch/ \
  -H "Authorization: ApiKey sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "user_id": "user-123",
        "event_type": "page_viewed",
        "payload": { "path": "/pricing" }
      },
      {
        "user_id": "user-456",
        "event_type": "trial_started",
        "payload": { "plan": "starter" }
      }
    ]
  }'
json
{ "queued": 2, "skipped": 0 }

skipped counts events dropped due to validation failures (malformed user_id, schema violations, etc.).

User Identification#

Send a context_identified event to set or update user-level properties:

bash
curl -X POST https://api.segops.ai/api/ingestion/track/ \
  -H "Authorization: ApiKey sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "event_type": "context_identified",
    "payload": {
      "email": "[email protected]",
      "plan": "starter",
      "company": "Acme Corp"
    }
  }'

Shopify Webhooks#

POST /api/ingestion/shopify/<tenant_slug>/

Receives Shopify webhook payloads. Authentication is via X-Shopify-Hmac-SHA256 header — no API key required. See the Shopify Integration guide for setup details.

Health Check#

GET /api/ingestion/health/

json
{
  "pubsub_topic": "ok",
  "worker": "ok",
  "clickhouse": "ok"
}

Stats#

GET /api/ingestion/stats/?window=24h

bash
curl "https://api.segops.ai/api/ingestion/stats/?window=24h" \
  -H "Authorization: Bearer $JWT"
json
{
  "window": "24h",
  "total_events": 142890,
  "unique_users": 8341,
  "timeseries": [
    { "bucket": "2026-04-25T13:00:00Z", "event_count": 5821, "unique_users": 342 }
  ],
  "event_types": [
    { "event_type": "page_viewed", "count": 87200 }
  ]
}

window accepts 24h or 7d.

Recent Errors#

GET /api/ingestion/errors/?limit=50

bash
curl "https://api.segops.ai/api/ingestion/errors/?limit=50" \
  -H "Authorization: Bearer $JWT"

Returns up to 100 recent error records with ts, error_type, and detail fields.