Events API

One-off events with tickets, registrations and a check-in list.

Module code happenings · 11 actions · 3 data models · 9 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: happenings (everything), happenings:read (read only) or happenings:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

happenings.cancel

Cancel the event — Cancels the event and releases every registration; the event names who was booked so they can be told.

Needs happenings:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/happenings.cancel

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: happenings.cancelled

What it writes: happening (update) — Marks it cancelled; happening_registration (update) — Releases the registrations

curl -X POST https://app.getera.io/api/v1/happenings/HAPPENING_ID/actions/cancel \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Reason"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "happenings.cancelled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.happenings.cancel("HAPPENING_ID", {
  reason: "Reason"
})

era happenings cancel HAPPENING_ID \
  --reason "Reason"

{
  "name": "era__happenings__cancel",
  "arguments": {
    "id": "HAPPENING_ID",
    "reason": "Reason"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold happenings:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 happening_not_found, happening_closed · 429 slow down

happenings.cancel_registration

Cancel a registration — Releases a person’s places.

Needs happenings:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/happenings.cancel_registration

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: happenings.registration_cancelled

What it writes: happening_registration (update) — Marks it cancelled

curl -X POST https://app.getera.io/api/v1/happening_registrations/HAPPENING_REGISTRATION_ID/actions/cancel_registration \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"Reason"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "happenings.registration_cancelled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.happeningRegistrations.cancelRegistration("HAPPENING_REGISTRATION_ID", {
  reason: "Reason"
})

era happening_registrations cancel_registration HAPPENING_REGISTRATION_ID \
  --reason "Reason"

{
  "name": "era__happenings__cancel_registration",
  "arguments": {
    "id": "HAPPENING_REGISTRATION_ID",
    "reason": "Reason"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold happenings:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 registration_not_found, registration_not_checkable · 429 slow down

happenings.check_in

Check in — Marks a registered person as arrived — from the door list, or by their door code.

Needs happenings:write · changes data

• Canonical address: POST /api/v1/actions/happenings.check_in

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: happenings.checked_in

What it writes: happening_registration (update) — Marks it checked in

curl -X POST https://app.getera.io/api/v1/happening_registrations/HAPPENING_REGISTRATION_ID/actions/check_in \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"happeningId":"HAPPENING_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "happenings.checked_in"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.happeningRegistrations.checkIn("HAPPENING_REGISTRATION_ID", {
  happeningId: "HAPPENING_ID"
})

era happening_registrations check_in HAPPENING_REGISTRATION_ID \
  --happening-id "HAPPENING_ID"

{
  "name": "era__happenings__check_in",
  "arguments": {
    "id": "HAPPENING_REGISTRATION_ID",
    "happeningId": "HAPPENING_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold happenings:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 registration_not_found, registration_not_checkable · 429 slow down

happenings.complete

Close the door list — Marks the event finished; whoever did not check in is recorded as not having come.

Needs happenings:write · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/happenings.complete

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: happenings.completed

What it writes: happening (update) — Marks it completed; happening_registration (update) — Marks the absent as no-shows

curl -X POST https://app.getera.io/api/v1/happenings/HAPPENING_ID/actions/complete \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "happenings.completed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.happenings.complete("HAPPENING_ID")

era happenings complete HAPPENING_ID

{
  "name": "era__happenings__complete",
  "arguments": {
    "id": "HAPPENING_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold happenings:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 happening_not_found, happening_not_published · 429 slow down

happenings.create

Create an event — A dated event with a number of places; add tickets, then open registration.

Needs happenings:write · changes data

• REST alias: POST /api/v1/happenings
• Canonical address: POST /api/v1/actions/happenings.create

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: happenings.created

What it writes: happening (insert) — Writes the draft event

curl -X POST https://app.getera.io/api/v1/happenings/actions/create \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Title","startsAt":"2026-11-02T09:00:00Z","endsAt":"2026-11-02T09:00:00Z","capacity":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "happenings.created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.happenings.create({
  title: "Title",
  startsAt: "2026-11-02T09:00:00Z",
  endsAt: "2026-11-02T09:00:00Z",
  capacity: 1
})

era happenings create \
  --title "Title" \
  --starts-at "2026-11-02T09:00:00Z" \
  --ends-at "2026-11-02T09:00:00Z" \
  --capacity 1

{
  "name": "era__happenings__create",
  "arguments": {
    "title": "Title",
    "startsAt": "2026-11-02T09:00:00Z",
    "endsAt": "2026-11-02T09:00:00Z",
    "capacity": 1
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold happenings:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_happening_time · 429 slow down

happenings.publish

Open registration — Publishes a draft event so people can be registered.

Needs happenings:write · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/happenings.publish

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: happenings.published

What it writes: happening (update) — Marks it published

curl -X POST https://app.getera.io/api/v1/happenings/HAPPENING_ID/actions/publish \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "happenings.published"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.happenings.publish("HAPPENING_ID")

era happenings publish HAPPENING_ID

{
  "name": "era__happenings__publish",
  "arguments": {
    "id": "HAPPENING_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold happenings:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 happening_not_found, happening_not_draft, happening_needs_ticket · 429 slow down

happenings.register

Register a person — Takes places on a ticket for a customer; the price is frozen and handed to finance by event.

Needs happenings:write · changes data

• REST alias: POST /api/v1/happening_registrations
• Canonical address: POST /api/v1/actions/happenings.register

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: happenings.registered

What it writes: happening_registration (insert) — Writes the registration with its door code

curl -X POST https://app.getera.io/api/v1/happening_registrations/actions/register \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"happeningId":"HAPPENING_ID","ticketId":"HAPPENING_TICKET_ID","customerId":"CUSTOMER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "happenings.registered"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.happeningRegistrations.create({
  happeningId: "HAPPENING_ID",
  ticketId: "HAPPENING_TICKET_ID",
  customerId: "CUSTOMER_ID"
})

era happening_registrations create \
  --happening-id "HAPPENING_ID" \
  --ticket-id "HAPPENING_TICKET_ID" \
  --customer-id "CUSTOMER_ID"

{
  "name": "era__happenings__register",
  "arguments": {
    "happeningId": "HAPPENING_ID",
    "ticketId": "HAPPENING_TICKET_ID",
    "customerId": "CUSTOMER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold happenings:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 happening_not_found, happening_not_open, customer_not_found, customer_archived, happening_ticket_not_found, already_registered, happening_full · 429 slow down

happenings.register_online

Register online — A visitor takes places on an event ticket from the site; the price is frozen and finance charges it like any registration.

Needs happenings:write · changes data · Also callable from a published site (visitor)

• Canonical address: POST /api/v1/actions/happenings.register_online

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: happenings.registered

What it writes: happening_registration (insert) — Writes the registration with its door code

Errors: 401 no or expired credential · 403 the credential does not hold happenings:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 guest_details_required, happening_full · 429 slow down

happenings.remove_ticket

Remove a ticket — Deletes an unused ticket; one people registered on is retired instead.

Needs happenings:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/happenings.remove_ticket

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: happenings.tickets_changed

What it writes: happening_ticket (delete) — Deletes an unused ticket; happening_ticket (update) — Retires a used one

curl -X POST https://app.getera.io/api/v1/happening_tickets/HAPPENING_TICKET_ID/actions/remove_ticket \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "happenings.tickets_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.happeningTickets.removeTicket("HAPPENING_TICKET_ID")

era happening_tickets remove_ticket HAPPENING_TICKET_ID

{
  "name": "era__happenings__remove_ticket",
  "arguments": {
    "id": "HAPPENING_TICKET_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold happenings:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 happening_ticket_not_found · 429 slow down

happenings.save_ticket

Save a ticket — A ticket type — its price, its own cap, and optionally the catalog item it is sold as.

Needs happenings:write · changes data

• Canonical address: POST /api/v1/actions/happenings.save_ticket

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: happenings.tickets_changed

What it writes: happening_ticket (upsert) — Writes the ticket

curl -X POST https://app.getera.io/api/v1/happening_tickets/HAPPENING_TICKET_ID/actions/save_ticket \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"happeningId":"HAPPENING_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "happenings.tickets_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.happeningTickets.saveTicket("HAPPENING_TICKET_ID", {
  happeningId: "HAPPENING_ID"
})

era happening_tickets save_ticket HAPPENING_TICKET_ID \
  --happening-id "HAPPENING_ID"

{
  "name": "era__happenings__save_ticket",
  "arguments": {
    "id": "HAPPENING_TICKET_ID",
    "happeningId": "HAPPENING_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold happenings:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 happening_not_found, happening_ticket_not_found, invalid_happening_ticket · 429 slow down

happenings.update

Edit an event — Changes the title, time, place or number of places.

Needs happenings:write · changes data

• REST alias: PATCH /api/v1/happenings/{id}
• Canonical address: POST /api/v1/actions/happenings.update

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: happenings.updated

What it writes: happening (update) — Rewrites the event

curl -X POST https://app.getera.io/api/v1/happenings/HAPPENING_ID/actions/update \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Title"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "happenings.updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.happenings.update("HAPPENING_ID", {
  title: "Title"
})

era happenings update HAPPENING_ID \
  --title "Title"

{
  "name": "era__happenings__update",
  "arguments": {
    "id": "HAPPENING_ID",
    "title": "Title"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold happenings:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 happening_not_found, happening_closed, invalid_happening_time, happening_capacity_below_taken · 429 slow down

Data models

HappeningRegistration

Table happening_registration · Resource happening_registrations

• GET /api/v1/happening_registrations
• GET /api/v1/happening_registrations/{id}
• POST /api/v1/happening_registrations → happenings.register

Primary key: id

Checks:

• CHECK ((currency ~ '^[A-Z]{3}$'::text))
• CHECK ((price_amount >= 0))
• CHECK (((quantity >= 1) AND (quantity <= 50)))

HappeningTicket

Table happening_ticket · Resource happening_tickets

• GET /api/v1/happening_tickets
• GET /api/v1/happening_tickets/{id}

Primary key: id

Checks:

• CHECK (((capacity IS NULL) OR (capacity > 0)))
• CHECK ((currency ~ '^[A-Z]{3}$'::text))
• CHECK ((length(TRIM(BOTH FROM name)) > 0))
• CHECK ((price_amount >= 0))

Happening

Table happening · Resource happenings

• GET /api/v1/happenings
• GET /api/v1/happenings/{id}
• POST /api/v1/happenings → happenings.create
• PATCH /api/v1/happenings/{id} → happenings.update

Primary key: id

Checks:

• CHECK ((capacity > 0))
• CHECK ((ends_at > starts_at))
• CHECK ((length(TRIM(BOTH FROM title)) > 0))

Events

Workflows and webhooks react to these events.