Events

Events are scheduled gatherings inside the community (a livestream, a live class, a webinar, an in-person meetup). Through the public API you list events, read a single event’s details, mark or unmark a user’s attendance, and, with admin scope, create and manage the full lifecycle. Think of an event like a party invitation: first you draft the invite without sending it (draft), then you hand it out (publish) and people RSVP (attend); if the party is off, you tell the people who signed up instead of pretending the invite never existed (cancel, not delete).

The lifecycle

Every event moves through three states. The transition always goes forward (you cannot “unpublish” an event; to take it down, cancel it).

Draft ──publish──> Published ──cancel──> Cancelled
                   (visible in           (visible as
                    the community)        cancelled)

Draft: created by POST /community/events. Invisible to members; use it to set up title, description, date and links before you announce.
Published: after POST /community/events/{eventId}/publish. Shows up in public listings and starts accepting attendance.
Cancelled: after POST /community/events/{eventId}/cancel. Stays visible (marked as cancelled) so anyone who signed up knows it is off.

publish and cancel are state transitions, not edits. To change the title, date or description of an existing event, use PUT /community/events/{eventId}. To remove the record entirely (instead of cancelling), use DELETE /community/events/{eventId}.

Optional link to a group or course

An event can be standalone (it appears on the community’s general agenda) or linked to a group or a course. The link is optional and adds context (a group’s event shows up inside that group; a course’s event shows up in the course track).

Standalone event  ──> community general agenda
Group event       ──> appears in the group (groupId)
Course event      ──> appears in the course (courseId)

To find the events of a specific group or course, use the filter endpoints:

# events of a group
curl https://apis.cativalab.digital/tenant/api/v2/community/events/by-group/01HQ0ABCDEF1234567890XYZ \
  -H "Authorization: Bearer cativa_live_..."

# events of a course
curl https://apis.cativalab.digital/tenant/api/v2/community/events/by-course/01HQ0COURSE1234567890XYZ \
  -H "Authorization: Bearer cativa_live_..."

Read endpoints

# list community events
curl https://apis.cativalab.digital/tenant/api/v2/community/events \
  -H "Authorization: Bearer cativa_live_..."

# single event detail
curl https://apis.cativalab.digital/tenant/api/v2/community/events/01HQ5EVENT1234567890XYZ \
  -H "Authorization: Bearer cativa_live_..."

# attendee list for the event
curl https://apis.cativalab.digital/tenant/api/v2/community/events/01HQ5EVENT1234567890XYZ/attendees \
  -H "Authorization: Bearer cativa_live_..."

We don’t document the field names of each response here (they evolve). Check the API Reference tab, under the Event tag, for the exact schema of every return.

Create an event (admin scope)

Creating, editing, publishing, cancelling and deleting events requires admin scope (organizer). Partner keys with default scope can read events and mark attendance, but they cannot create or change the lifecycle. Use a key with admin/organizer permission for the write endpoints. The event starts as a draft. Publish it as a second step, once it’s ready to announce.

Create the draft

POST /community/events with title, dates and (optionally) groupId or courseId. The response carries the event id. It starts invisible to members.

Publish

POST /community/events/{eventId}/publish. The event starts showing in listings and accepting attendance.

Collect attendance

Members call POST .../attend. Track who signed up through the attendees list.

Cancel if needed

POST /community/events/{eventId}/cancel keeps the event visible as cancelled for anyone who already signed up. To drop the record entirely, use DELETE.

# creates the event as a DRAFT; groupId and courseId are optional (link)
curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/events \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Kickoff livestream",
    "description": "July cohort kickoff.",
    "startsAt": "2026-08-01T19:00:00Z",
    "endsAt": "2026-08-01T20:30:00Z",
    "groupId": "01HQ5GROUP1234567890XYZ"
  }'

const res = await fetch('https://apis.cativalab.digital/tenant/api/v2/community/events', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`, // key with admin/organizer scope
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Kickoff livestream',
    description: 'July cohort kickoff.',
    startsAt: '2026-08-01T19:00:00Z',
    endsAt: '2026-08-01T20:30:00Z',
    groupId: '01HQ5GROUP1234567890XYZ' // optional; omit for a standalone event
  })
});
const event = await res.json();

// second step: publish when it's ready
await fetch(`https://apis.cativalab.digital/tenant/api/v2/community/events/${event.id}/publish`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

Creation returns the event identifier (use it in the publish, cancel and attend steps). Full schema in the API Reference tab, tag Event:

{
  "id": "01HQ5EVENT1234567890XYZ"
}

Without admin scope, the write endpoints (create, edit, publish, cancel, delete) return 403 forbidden. That’s expected: ask the tenant admin for an organizer key, or leave event creation to the dashboard.

Mark attendance (attend)

Any user with access to the event marks attendance with POST .../attend and removes it with DELETE .../attend. Attendance is always for the user tied to the authenticated credential (you don’t send userId in the body).

# mark attendance
curl -X POST https://apis.cativalab.digital/tenant/api/v2/community/events/01HQ5EVENT1234567890XYZ/attend \
  -H "Authorization: Bearer cativa_live_..."

# unmark attendance
curl -X DELETE https://apis.cativalab.digital/tenant/api/v2/community/events/01HQ5EVENT1234567890XYZ/attend \
  -H "Authorization: Bearer cativa_live_..."

The event must be published and the user must have access to the community (and to the group, if the event is linked to a group that requires a badge). Without access, it returns 403 forbidden. Once confirmed, attendance shows up in the event’s attendees list.

Common errors and questions

I created the event but nobody can see it

It’s probably still a draft. Drafts are invisible to members on purpose. Call POST /community/events/{eventId}/publish to take it live. Only after publishing does it show in listings and accept attendance.

How do I unpublish an event?

There is no “unpublish”. The transition always moves forward (draft, published, cancelled). To take down an announced event, use cancel: it stays visible marked as cancelled so anyone who signed up knows it’s off. DELETE removes the record entirely (with no notice to attendees).

403 forbidden when creating or publishing

Writes (create, edit, publish, cancel, delete) require admin scope (organizer). A default partner key only reads events and marks attendance. Ask the tenant admin for an organizer key, or leave creation to the dashboard.

403 forbidden marking attendance on an event I can see in the listing

Seeing it in the listing isn’t the same as having access to the event. If the event is linked to a group that requires a badge, the user needs that badge to attend. Assign the badge (see Badges as Permissions) and retry attend.

I marked attendance twice, is that a problem?

No. Marking again is safe: attendance belongs to the credential’s user and does not duplicate. DELETE .../attend unmarks it; unmarking something that wasn’t marked does not error. Treat the attend/unattend pair as idempotent.

Next steps

Communities and Spaces

The Community > Space > Group hierarchy where events can be linked.

Courses and Certificates

How to link an event to a course and its lesson track.

Posts and Comments

Post to the group feed to announce and follow up on an event.

Get Started

Concepts

Guides

Webhooks

Changelog

The lifecycle

Optional link to a group or course

Read endpoints

Create an event (admin scope)

Mark attendance (attend)

Common errors and questions

Next steps

Communities and Spaces

Courses and Certificates

Posts and Comments

​The lifecycle

​Optional link to a group or course

​Read endpoints

​Create an event (admin scope)

​Mark attendance (attend)

​Common errors and questions

​Next steps

Communities and Spaces

Courses and Certificates

Posts and Comments

The lifecycle

Optional link to a group or course

Read endpoints

Create an event (admin scope)

Mark attendance (attend)

Common errors and questions

Next steps