Ingestion API

The ingestion endpoint receives events from SDKs.

Endpoint

POST /api/ingest

Request

{
  "projectId": "uuid",
  "sessionId": "uuid",
  "user": {
    "id": "user-123",
    "email": "user@example.com",
    "name": "John Doe"
  },
  "release": {
    "release": "1.2.3",
    "dist": "45",
    "environment": "production",
    "updateId": "expo-update-id",
    "updateChannel": "production"
  },
  "events": [
    {
      "type": "error",
      "timestamp": "2024-01-15T10:00:00.000Z",
      "payload": {
        "message": "Cannot read property 'id' of undefined",
        "stack": "Error: Cannot read...\n    at foo.js:10:5",
        "breadcrumbs": [
          {
            "timestamp": "2024-01-15T09:59:55.000Z",
            "category": "navigation",
            "message": "Navigate to /checkout"
          }
        ],
        "context": {
          "browser": { "name": "Chrome", "version": "120" },
          "os": { "name": "macOS", "version": "14.0" }
        },
        "tags": { "component": "checkout" },
        "extra": { "orderId": "123" },
        "severity": "error"
      }
    }
  ]
}

Request Fields

Required

Field	Type	Description
projectId	uuid	Your project ID
sessionId	uuid	Client-generated session ID
events	array	Array of events (1-100)

Optional

Field	Type	Description
user	object	User identification
release	object	Release/version info

Event Object

Field	Type	Description
type	string	"error", "pageview", "custom"
timestamp	string	ISO 8601 timestamp
name	string	Event name (for custom events)
payload	object	Event-specific data

Error Payload

Field	Type	Description
message	string	Error message
stack	string	Stack trace
breadcrumbs	array	Breadcrumb trail
context	object	Runtime context
tags	object	Indexed key-value pairs
extra	object	Additional data
severity	string	"fatal", "error", "warning", "info"

Pageview Payload

Field	Type	Description
url	string	Page URL
referrer	string	Referrer URL
title	string	Page title

Response

Success (202 Accepted)

{
  "success": true,
  "eventIds": ["uuid-1", "uuid-2"],
  "sessionId": "session-uuid"
}

Error (400 Bad Request)

{
  "success": false,
  "error": "Invalid request",
  "details": [
    {
      "path": ["projectId"],
      "message": "Invalid uuid"
    }
  ]
}

Error (401 Unauthorized)

{
  "success": false,
  "error": "Invalid or inactive project"
}

Example: cURL

curl -X POST https://syntropy.chat/api/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "your-project-id",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "events": [{
      "type": "error",
      "timestamp": "2024-01-15T10:00:00.000Z",
      "payload": {
        "message": "Test error",
        "severity": "error"
      }
    }]
  }'

Batching

The SDK batches events for efficiency. You can send up to 100 events per request.

Idempotency

Events are deduplicated by (sessionId, timestamp, type, payload). Sending the same event twice won't create duplicates.