Events

Track an event

POST/v1/events/track

Requires an API key with the events:write scope. About keys and scopes

Takes an Idempotency-Key header: a retry with the same key returns the first result instead of acting twice. Derive the key from what you are sending, and reuse it on every retry. About idempotency

Records a behavioural event against a contact. Events drive journey triggers and segment rules, so this is the main ingestion endpoint for product activity. The event and its processing obligation are stored atomically: a 201 confirms storage, while journey and conversion effects run asynchronously afterwards. Name the contact by exactly one of contactId, externalId or email; a contact that does not exist is a 404, never created. occurredAt may be at most 24 hours in the future. Names are case-sensitive, up to 128 characters with no control characters; those beginning with contact. are reserved for platform events. A workspace tracks at most 1,000 distinct names: a new one past that is refused with EVENT_NAME_LIMIT_REACHED, so keep ids and prices in properties. A repeated Idempotency-Key answers the event first stored, with Idempotency-Replay: true.

Header parameters

Idempotency-Keystringrequired: 8–255 characters

Request body

By contact id

5 child attributes

contactIdstringrequired

Kirora's id for the contact.

uuid

eventNamestringrequired

Case-sensitive, up to 128 characters; contact.* is reserved.

1–128 characters

propertiesobjectoptional

Free-form details of the event; at most 16 KB, keys up to 64 characters.

default {}

occurredAtstringoptional

When it happened; defaults to now. At most 24 hours ahead.

date-time

contextEventContextInputoptional

Where and on what it happened, beside the properties.

9 child attributes

sessionIdstringoptional

The visit, from the SDK.

up to 128 characters

localestringoptional

As BCP 47, en-GB.

up to 35 characters

timezonestringoptional

As IANA, Europe/Berlin.

up to 64 characters

pageobjectoptional

Web: the page, without its query string or fragment.

4 child attributes

urlstringoptional: up to 2048 characters
pathstringoptional: up to 2048 characters
titlestringoptional: up to 256 characters
referrerstringoptional: up to 2048 characters

campaignobjectoptional

Web: the utm_* parameters of the page.

5 child attributes

sourcestringoptional: up to 256 characters
mediumstringoptional: up to 256 characters
namestringoptional: up to 256 characters
termstringoptional: up to 256 characters
contentstringoptional: up to 256 characters

deviceobjectoptional

1 child attribute

idstringoptional

A random id the SDK keeps on the device; never a hardware id.

up to 128 characters

libraryobjectoptional

2 child attributes

namestringoptional: up to 64 characters
versionstringoptional: up to 64 characters

ipstringoptional

up to 64 characters

userAgentstringoptional

up to 1024 characters

By external id

5 child attributes

externalIdstringrequired

Your own id for the contact, as set with identify.

1–255 characters

eventNamestringrequired

Case-sensitive, up to 128 characters; contact.* is reserved.

1–128 characters

propertiesobjectoptional

Free-form details of the event; at most 16 KB, keys up to 64 characters.

default {}

occurredAtstringoptional

When it happened; defaults to now. At most 24 hours ahead.

date-time

contextEventContextInputoptional

Where and on what it happened, beside the properties.

9 child attributes

sessionIdstringoptional

The visit, from the SDK.

up to 128 characters

localestringoptional

As BCP 47, en-GB.

up to 35 characters

timezonestringoptional

As IANA, Europe/Berlin.

up to 64 characters

pageobjectoptional

Web: the page, without its query string or fragment.

4 child attributes

urlstringoptional: up to 2048 characters
pathstringoptional: up to 2048 characters
titlestringoptional: up to 256 characters
referrerstringoptional: up to 2048 characters

campaignobjectoptional

Web: the utm_* parameters of the page.

5 child attributes

sourcestringoptional: up to 256 characters
mediumstringoptional: up to 256 characters
namestringoptional: up to 256 characters
termstringoptional: up to 256 characters
contentstringoptional: up to 256 characters

deviceobjectoptional

1 child attribute

idstringoptional

A random id the SDK keeps on the device; never a hardware id.

up to 128 characters

libraryobjectoptional

2 child attributes

namestringoptional: up to 64 characters
versionstringoptional: up to 64 characters

ipstringoptional

up to 64 characters

userAgentstringoptional

up to 1024 characters

By email

5 child attributes

emailstringrequired

The contact's email address, matched trimmed and without case.

eventNamestringrequired

Case-sensitive, up to 128 characters; contact.* is reserved.

1–128 characters

propertiesobjectoptional

Free-form details of the event; at most 16 KB, keys up to 64 characters.

default {}

occurredAtstringoptional

When it happened; defaults to now. At most 24 hours ahead.

date-time

contextEventContextInputoptional

Where and on what it happened, beside the properties.

9 child attributes

sessionIdstringoptional

The visit, from the SDK.

up to 128 characters

localestringoptional

As BCP 47, en-GB.

up to 35 characters

timezonestringoptional

As IANA, Europe/Berlin.

up to 64 characters

pageobjectoptional

Web: the page, without its query string or fragment.

4 child attributes

urlstringoptional: up to 2048 characters
pathstringoptional: up to 2048 characters
titlestringoptional: up to 256 characters
referrerstringoptional: up to 2048 characters

campaignobjectoptional

Web: the utm_* parameters of the page.

5 child attributes

sourcestringoptional: up to 256 characters
mediumstringoptional: up to 256 characters
namestringoptional: up to 256 characters
termstringoptional: up to 256 characters
contentstringoptional: up to 256 characters

deviceobjectoptional

1 child attribute

idstringoptional

A random id the SDK keeps on the device; never a hardware id.

up to 128 characters

libraryobjectoptional

2 child attributes

namestringoptional: up to 64 characters
versionstringoptional: up to 64 characters

ipstringoptional

up to 64 characters

userAgentstringoptional

up to 1024 characters

Returns

Returns 201 Created with a TrackedEvent in data. Otherwise returns an error; Errors lists every code and which to retry.

idstringrequired: uuid
occurredAtstringrequired: date-time

curl -X POST https://api.kirora.io/v1/events/track \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Idempotency-Key: cart-7731-abandoned" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
    "eventName": "Cart Abandoned",
    "occurredAt": "2026-10-01T09:30:00Z"
  }'

const response = await fetch('https://api.kirora.io/v1/events/track', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Idempotency-Key': "cart-7731-abandoned",
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
    "eventName": "Cart Abandoned",
    "occurredAt": "2026-10-01T09:30:00Z"
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/events/track",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
        "Idempotency-Key": "cart-7731-abandoned",
    },
    json={
        "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
        "eventName": "Cart Abandoned",
        "occurredAt": "2026-10-01T09:30:00Z",
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
	  "eventName": "Cart Abandoned",
	  "occurredAt": "2026-10-01T09:30:00Z"
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/events/track", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Idempotency-Key", "cart-7731-abandoned")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 201

{
  "data": {
    "id": "0192f3c0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "occurredAt": "2026-10-01T09:30:00.000Z"
  }
}

curl -X POST https://api.kirora.io/v1/events/track \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Idempotency-Key: order-1001-completed" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "customer-4821",
    "eventName": "Order Completed",
    "properties": {
      "order_id": "1001",
      "total": 46.5,
      "currency": "USD",
      "products": [
        {
          "name": "Smoked paprika",
          "quantity": 3,
          "price": 15.5
        }
      ]
    },
    "occurredAt": "2026-10-01T09:30:00Z"
  }'

const response = await fetch('https://api.kirora.io/v1/events/track', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Idempotency-Key': "order-1001-completed",
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "externalId": "customer-4821",
    "eventName": "Order Completed",
    "properties": {
      "order_id": "1001",
      "total": 46.5,
      "currency": "USD",
      "products": [
        {
          "name": "Smoked paprika",
          "quantity": 3,
          "price": 15.5
        }
      ]
    },
    "occurredAt": "2026-10-01T09:30:00Z"
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/events/track",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
        "Idempotency-Key": "order-1001-completed",
    },
    json={
        "externalId": "customer-4821",
        "eventName": "Order Completed",
        "properties": {
            "order_id": "1001",
            "total": 46.5,
            "currency": "USD",
            "products": [
                {
                    "name": "Smoked paprika",
                    "quantity": 3,
                    "price": 15.5,
                },
            ],
        },
        "occurredAt": "2026-10-01T09:30:00Z",
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "externalId": "customer-4821",
	  "eventName": "Order Completed",
	  "properties": {
	    "order_id": "1001",
	    "total": 46.5,
	    "currency": "USD",
	    "products": [
	      {
	        "name": "Smoked paprika",
	        "quantity": 3,
	        "price": 15.5
	      }
	    ]
	  },
	  "occurredAt": "2026-10-01T09:30:00Z"
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/events/track", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Idempotency-Key", "order-1001-completed")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 201

{
  "data": {
    "id": "0192f3c0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "occurredAt": "2026-10-01T09:30:00.000Z"
  }
}

curl -X POST https://api.kirora.io/v1/events/track \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Idempotency-Key: checkout-5520-started" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "amaka@example.com",
    "eventName": "Checkout Started"
  }'

const response = await fetch('https://api.kirora.io/v1/events/track', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Idempotency-Key': "checkout-5520-started",
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "amaka@example.com",
    "eventName": "Checkout Started"
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/events/track",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
        "Idempotency-Key": "checkout-5520-started",
    },
    json={
        "email": "amaka@example.com",
        "eventName": "Checkout Started",
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "email": "amaka@example.com",
	  "eventName": "Checkout Started"
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/events/track", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Idempotency-Key", "checkout-5520-started")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 201

{
  "data": {
    "id": "0192f3c0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "occurredAt": "2026-10-01T09:30:00.000Z"
  }
}