Define or describe an event nameMenu

Define or describe an event name

PUT/v1/events/catalog/{name}

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

Works with integration and partner keys, not agent keys.

Safe to retry: a repeat sets the same values again. About idempotency

Adds a name to the catalogue before the app sends it, so a journey, segment or goal can be built on it while the app's developers add it, or sets the description of a name already listed. Sending events with exactly this name then fills its figures. A name new to the workspace counts against its limit, and past it is refused with EVENT_NAME_LIMIT_REACHED; a name being deleted is 409 CONFLICT. contact.* names and Ordered Product are recorded by Kirora and refused. On /v1 it takes events:write, which an agent key cannot hold.

Path parameters

namestringrequired

The event name, exactly as it is tracked, URL-encoded (Order%20Completed).

pattern ^\P{Cc}+$ · 1–128 characters

Header parameters

Kirora-Workspacestringoptional

Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

pattern ^[A-Za-z0-9._:-]{1,128}$

Request body

descriptionstring | nullrequired

What the event means, at most 255 characters: shown in the lists and pickers, and read by Kiro. null removes it.

1–255 characters

Returns

Returns 200 OK with an EventName in data. It can also return 409 Conflict, 413 Payload Too Large or 415 Unsupported Media Type; see the statuses below. Otherwise returns an error; Errors lists every code and which to retry.

200 OKThe name as the catalogue lists it.
409 ConflictThe request conflicts with current state — a duplicate unique value, or a resource whose status does not allow this operation.
413 Payload Too LargeThe body is larger than this operation accepts (PAYLOAD_TOO_LARGE).
415 Unsupported Media TypeThe body is not JSON, or not the upload the operation takes (UNSUPPORTED_MEDIA_TYPE).

namestringrequired

originstringrequired

one of system, standard, custom

recordedbooleanrequired

Whether the workspace has events of it. False for a name defined before it was sent, and for a system name Kirora has not recorded yet.

descriptionstring | nullrequired

The workspace's description, else Kirora's meaning for a system or standard name; null when neither. Plain text.

lastSeenAtstring | nullrequired

When its latest event happened; null when it has none.

date-time

last30DaysCountintegerrequired

Events of it that happened in the last 30 days.

min 0

usedByCountintegerrequired

Journeys, segments, campaigns, conversion goals and active workspace goals that read it; the summary names them.

min 0

curl -X PUT https://api.kirora.io/v1/events/catalog/Order%20Completed \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A contact moved to a paid plan."
  }'

const response = await fetch('https://api.kirora.io/v1/events/catalog/Order%20Completed', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "description": "A contact moved to a paid plan."
  }),
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.put(
    "https://api.kirora.io/v1/events/catalog/Order%20Completed",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "description": "A contact moved to a paid plan.",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "description": "A contact moved to a paid plan."
	}`)
	req, err := http.NewRequest("PUT", "https://api.kirora.io/v1/events/catalog/Order%20Completed", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

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

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Put, "https://api.kirora.io/v1/events/catalog/Order%20Completed");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));
request.Content = new StringContent(
    """
    {
      "description": "A contact moved to a paid plan."
    }
    """,
    Encoding.UTF8,
    "application/json");

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 200

{
  "data": {
    "name": "Plan Upgraded",
    "origin": "custom",
    "recorded": false,
    "description": "A contact moved to a paid plan.",
    "lastSeenAt": null,
    "last30DaysCount": 0,
    "usedByCount": 0
  }
}