API and Examples

Event Payload Examples

Copy-paste examples for common Logga ingest patterns.

This page collects examples that are useful when wiring integrations or explaining the Logga data model to other teams.

Minimal Event

json

{
  "channel": "system",
  "event": "deploy_completed"
}

Event With Metadata

json

{
  "channel": "payments",
  "event": "invoice_sent",
  "level": "success",
  "metadata": {
    "invoiceId": "inv_123",
    "amount": 49,
    "currency": "EUR"
  }
}

Event With Actor Snapshot

json

{
  "channel": "auth",
  "event": "signed_in",
  "actor": {
    "id": "user_123",
    "name": "Francesco",
    "email": "[email protected]",
    "role": "admin",
    "label": "Francesco V."
  }
}

Event With Custom Actor Properties

actor.properties is a free-form object for fields that do not fit the reserved identity columns (name, email, avatarUrl, role, label). Values must be strings, numbers, booleans, or null. Up to 50 keys per user, keys ≤64 chars, string values ≤1024 chars.

json

{
  "channel": "billing",
  "event": "subscription_updated",
  "actor": {
    "id": "user_123",
    "name": "Francesco",
    "email": "[email protected]",
    "properties": {
      "plan": "pro",
      "seats": 5,
      "trial": false,
      "signup_source": "landing_cta"
    }
  }
}

Every event with an actor.id upserts the matching tracked user and updates any identity field carried in the payload. Fields omitted from the payload are left untouched.

Properties work as a patch, not a replacement: keys in actor.properties are written, keys you leave out keep their value, and a key sent as null is removed. So a billing job can send { "plan": "pro" } and a login can send { "last_login_method": "google" } without erasing each other. Two events for the same user arriving together keep both sets of keys.

If actor.properties breaks the limits above, or would take the user past 50 keys in total, the event is still stored but the properties are not, and the response carries a warnings array saying why. Free space by sending the keys you no longer need as null.

Event With Stable User ID Only

json

{
  "channel": "auth",
  "event": "signed_in",
  "userId": "user_123"
}

Use this shape when you do not have a full actor snapshot available. The dashboard Users view can still track the user because the event carries a stable id.

Event With Tags And Idempotency

json

{
  "channel": "payments",
  "event": "payment_succeeded",
  "level": "success",
  "tags": ["stripe", "subscription", "seed"],
  "metadata": {
    "amount": 4999,
    "currency": "USD"
  },
  "idempotencyKey": "payment_987654"
}

Session Start

json

{
  "channel": "system",
  "name": "nightly_build",
  "metadata": {
    "branch": "main",
    "commit": "abc123"
  },
  "ttlSeconds": 1800
}

Session Progress Update

json

{
  "currentStep": "Running integration tests",
  "progress": 60,
  "metadata": {
    "suite": "smoke"
  }
}

Session Completion

json

{
  "summary": "Build finished successfully and was deployed to sandbox."
}

Curl Example

bash

curl -X POST https://api.logga.sh/v1/events \
  -H "Authorization: Bearer lg_sk_test_1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "payments",
    "event": "invoice_sent",
    "level": "success",
    "metadata": {
      "amount": 49
    }
  }'

TypeScript Example

await fetch("https://api.logga.sh/v1/events", {
  method: "POST",
  headers: {
    Authorization: "Bearer lg_sk_test_1234567890",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "auth",
    event: "login_failed",
    level: "warning",
    actor: {
      id: "user_123",
      email: "[email protected]",
    },
    metadata: {
      reason: "invalid_password",
    },
  }),
})

Tracking Users In The Dashboard

To make a product user appear in the dashboard Users view:

prefer actor.id
fall back to userId
keep the same stable id across events for the same person

If neither field is present, the event still ingests but contributes only to unattributed activity.

Identity source of truth

Identity fields (name, email, avatarUrl, role, label) and custom properties can come from either the SDK or the dashboard editor. When an event arrives with a field set in the actor payload, Logga overwrites the tracked user's value for that field. Dashboard edits persist until the next event carries a different value for that same field — send the final state from the SDK to make it authoritative, or edit it once in the dashboard and omit that field from outgoing events.

API Reference

Route families, auth model, and copy-paste request examples.

Instrumentation Recipes

Node, Next.js, Python, Go, Swift and shell versions of the same small client, with real call sites.