# Define or describe an event name

Source: https://kirora.io/docs/api/reference/defineEventName

`PUT /v1/events/catalog/{name}`

Requires an API key with the `events:write` scope. [About keys and scopes](https://kirora.io/docs/api/reference/authentication)

Works with integration and partner keys, not agent keys.

Safe to retry: a repeat sets the same values again. [About idempotency](https://kirora.io/docs/api/reference/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

- `name` (string, required, pattern `^\P{Cc}+$`, 1–128 characters) — The event name, exactly as it is tracked, URL-encoded (`Order%20Completed`).

## Header parameters

- `Kirora-Workspace` (string, optional, pattern `^[A-Za-z0-9._:-]{1,128}$`) — 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.

## Request body

- `description` (string | null, required, 1–255 characters) — What the event means, at most 255 characters: shown in the lists and pickers, and read by Kiro. `null` removes it.

## 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](https://kirora.io/docs/api/reference/errors) lists every code and which to retry.

- `name` (string, required)
- `origin` (string, required, one of `system`, `standard`, `custom`)
- `recorded` (boolean, required) — 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.
- `description` (string | null, required) — The workspace's description, else Kirora's meaning for a system or standard name; null when neither. Plain text.
- `lastSeenAt` (string | null, required, date-time) — When its latest event happened; null when it has none.
- `last30DaysCount` (integer, required, min 0) — Events of it that happened in the last 30 days.
- `usedByCount` (integer, required, min 0) — Journeys, segments, campaigns, conversion goals and active workspace goals that read it; the summary names them.

Statuses:

- `200 OK`: The name as the catalogue lists it.
- `409 Conflict`: The request conflicts with current state — a duplicate unique value, or a resource whose status does not allow this operation.
- `413 Payload Too Large`: The body is larger than this operation accepts (`PAYLOAD_TOO_LARGE`).
- `415 Unsupported Media Type`: The body is not JSON, or not the upload the operation takes (`UNSUPPORTED_MEDIA_TYPE`).

## Example: Define a name before the app sends it

```bash
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."
  }'
```

Response `200`:

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