Nookhive Logo
StyleguideAPI Reference

Events API

Create, manage, and publish events through the NookHive API.

Overview

The Events API allows you to create and manage events, including ticket types, scheduling, and publication status. Events are the core resource that bookings and registrations are associated with.

All endpoints require organization-level API key authentication.

Base Path

https://api.nookhive.com/v1/events

Endpoints

GET/v1/events

List Events

Returns a paginated list of all events in your organization. Results are sorted by creation date, with the most recent events first.

Parameters

NameTypeDescription
pageintegerPage number for pagination (default: 1)
limitintegerNumber of results per page (default: 20, max: 100)
statusstringFilter by status: DRAFT, PUBLISHED, CANCELLED, COMPLETED
Example RequestBASH
curl -X GET "https://api.nookhive.com/v1/events?status=PUBLISHED" \
  -H "Authorization: Bearer nk_live_your_api_key_here"
ResponseJSON
{
  "events": [
    {
      "id": "evt_example123",
      "slug": "annual-conference-2026",
      "title": "Annual Conference 2026",
      "description": "Our annual gathering of industry professionals",
      "startDate": "2026-03-15T09:00:00Z",
      "endDate": "2026-03-15T18:00:00Z",
      "timezone": "Asia/Shanghai",
      "venue": "Shanghai Convention Center",
      "status": "PUBLISHED",
      "capacity": 500,
      "registrationCount": 234,
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-15T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}
GET/v1/events/{slug}

Get Event Details

Retrieve detailed information about a specific event, including ticket types and configuration.

Parameters

NameTypeDescription
slug*stringThe unique slug identifier of the event
Example RequestBASH
curl -X GET "https://api.nookhive.com/v1/events/annual-conference-2026" \
  -H "Authorization: Bearer nk_live_your_api_key_here"
POST/v1/events

Create Event

Create a new event in your organization. The event will be created in DRAFT status by default.

Parameters

NameTypeDescription
title*stringEvent title
slug*stringURL-friendly unique identifier
descriptionstringEvent description (supports markdown)
startDate*ISO 8601Event start date and time
endDate*ISO 8601Event end date and time
timezonestringIANA timezone (default: organization timezone)
venuestringEvent venue or location
capacityintegerMaximum number of attendees
Example RequestBASH
curl -X POST "https://api.nookhive.com/v1/events" \
  -H "Authorization: Bearer nk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer Workshop 2026",
    "slug": "summer-workshop-2026",
    "description": "A hands-on workshop for professionals",
    "startDate": "2026-06-15T09:00:00Z",
    "endDate": "2026-06-15T17:00:00Z",
    "timezone": "Asia/Shanghai",
    "venue": "NookHive HQ",
    "capacity": 50
  }'
PUT/v1/events/{slug}

Update Event

Update an existing event. Only provided fields will be updated.

Parameters

NameTypeDescription
slug*stringThe unique slug identifier of the event
titlestringEvent title
descriptionstringEvent description
statusstringEvent status: DRAFT, PUBLISHED, CANCELLED
Example RequestBASH
curl -X PUT "https://api.nookhive.com/v1/events/summer-workshop-2026" \
  -H "Authorization: Bearer nk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "PUBLISHED"
  }'
JavaScript ExampleJAVASCRIPT
const response = await fetch(
  'https://api.nookhive.com/v1/events/summer-workshop-2026',
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer nk_live_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ status: 'PUBLISHED' })
  }
);

const event = await response.json();
console.log('Event published:', event.slug);
DELETE/v1/events/{slug}

Delete Event

Delete an event. This action cannot be undone. Events with existing bookings cannot be deleted - cancel them first.

Parameters

NameTypeDescription
slug*stringThe unique slug identifier of the event
Example RequestBASH
curl -X DELETE "https://api.nookhive.com/v1/events/summer-workshop-2026" \
  -H "Authorization: Bearer nk_live_your_api_key_here"
Success Response (204 No Content)BASH
# No response body returned on successful deletion
Error Response (409 Conflict)JSON
{
  "error": {
    "code": "EVENT_HAS_BOOKINGS",
    "message": "Cannot delete event with existing bookings. Cancel the event instead.",
    "details": {
      "bookingCount": 15
    }
  }
}

Error Responses

Common error responses you may encounter when using the Events API:

404 Not Found - Event Not Found

{
  "error": {
    "code": "EVENT_NOT_FOUND",
    "message": "The requested event was not found.",
    "details": {
      "slug": "invalid-event-slug"
    }
  }
}

400 Bad Request - Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "errors": [
        { "field": "startDate", "message": "Start date must be in the future" },
        { "field": "slug", "message": "Slug already exists" }
      ]
    }
  }
}

409 Conflict - Event Published

{
  "error": {
    "code": "EVENT_ALREADY_PUBLISHED",
    "message": "Cannot modify certain fields on a published event.",
    "details": {
      "immutableFields": ["slug", "startDate"]
    }
  }
}

The Event Object

{
  "id": "evt_example123",
  "slug": "annual-conference-2026",
  "title": "Annual Conference 2026",
  "description": "Our annual gathering of industry professionals",
  "startDate": "2026-03-15T09:00:00Z",
  "endDate": "2026-03-15T18:00:00Z",
  "timezone": "Asia/Shanghai",
  "venue": "Shanghai Convention Center",
  "venueAddress": "123 Convention Road, Shanghai",
  "coverImage": "https://files.nookhive.com/events/cover123.jpg",
  "status": "PUBLISHED",
  "capacity": 500,
  "registrationCount": 234,
  "ticketTypes": [
    {
      "id": "tt_standard",
      "name": "Standard Ticket",
      "price": 199.00,
      "currency": "USD",
      "quantity": 400,
      "sold": 200
    }
  ],
  "organizationId": "org_abc123",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-15T12:00:00Z"
}