Event Categories

The Event Categories API allows you to create, retrieve, update, and delete categories for organizing and classifying events. Categories help users discover and filter events based on their interests.

Authentication

All requests to the Event Categories API must be authenticated using the ONLIVE.SITE authentication scheme. Please refer to the Authentication Guide for detailed instructions.

Base URL

https://openapi.onlive.site/api/v1/event-categories

Endpoints

• Create Category
• Get Category
• Update Category
• Search Categories
• Delete Category

---

Create Category

Creates a new event category.

HTTP Request

POST /api/v1/event-categories

Request Body

Field	Type	Required	Description
name	string	Yes	The name of the category (max 255 characters)
description	string	No	The description of the category
userGroupId	string (uuid)	No	When provided, takes precedence over the authenticated user's user group ID
organizationId	string (uuid)	No	The organization identifier

Example Request Body

{
  "name": "Technology",
  "description": "Technology-related events and conferences"
}

Response

201 Created

Returns the created EventCategory object.

Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Technology",
  "slug": "technology",
  "description": "Technology-related events and conferences",
  "organization": {
    "id": "987e6543-e21a-34b5-c678-426614174000",
    "name": "Tech Events Inc"
  },
  "createdAt": "2025-10-13T10:30:00.000Z",
  "updatedAt": "2025-10-13T10:30:00.000Z"
}

---

Get Category

Retrieves a specific event category by its ID.

HTTP Request

GET /api/v1/event-categories/{id}

Path Parameters

Parameter	Type	Required	Description
id	string (uuid)	Yes	The unique identifier of the category

Query Parameters

Parameter	Type	Required	Description
withTrashed	boolean	No	Include trashed categories

Response

200 OK

Returns the EventCategory object.

Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Technology",
  "slug": "technology",
  "description": "Technology-related events and conferences",
  "organization": {
    "id": "987e6543-e21a-34b5-c678-426614174000",
    "name": "Tech Events Inc"
  },
  "createdAt": "2025-10-13T10:30:00.000Z",
  "updatedAt": "2025-10-13T10:30:00.000Z"
}

---

Update Category

Updates an existing event category.

HTTP Request

PUT /api/v1/event-categories/{id}

Path Parameters

Parameter	Type	Required	Description
id	string (uuid)	Yes	The unique identifier of the category to update

Request Body

All fields are optional. Only the fields you want to update need to be included.

Field	Type	Required	Description
name	string	No	The name of the category (max 255 characters)
description	string	No	The description of the category
userGroupId	string (uuid)	No	When provided, takes precedence over the authenticated user's user group ID
organizationId	string (uuid)	No	The organization identifier

Example Request Body

{
  "name": "Tech & Innovation",
  "description": "Technology and innovation-related events, conferences, and workshops"
}

Response

200 OK

Returns the updated EventCategory object.

Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Tech & Innovation",
  "slug": "tech-innovation",
  "description": "Technology and innovation-related events, conferences, and workshops",
  "organization": {
    "id": "987e6543-e21a-34b5-c678-426614174000",
    "name": "Tech Events Inc"
  },
  "createdAt": "2025-10-13T10:30:00.000Z",
  "updatedAt": "2025-10-13T14:00:00.000Z"
}

---

Search Categories

Returns a paginated list of event categories with optional filtering and sorting.

HTTP Request

GET /api/v1/event-categories

Query Parameters

Parameter	Type	Required	Description
limit	number	No	Maximum number of items to return (default: 10, min: 1, example: 20)
page	number	No	Page number (starts at 1, default: 1, min: 1, example: 1)
sort	string	No	Field name and direction to sort results by. Use "ASC" or "DESC" (default: "createdAt DESC", example: "createdAt DESC")
organizationId	string (uuid)	No	Filter categories by organization ID
search	string	No	Search term to filter categories by name (example: "tech")
timeRange	string	No	Time range filter for events: upcoming, past, or all (example: "upcoming")
channelType	string	No	Filter events by publishing channel type: WEBSITE, MOBILE_APP, SOCIAL_MEDIA, EMAIL, OTHER (example: "WEBSITE")
channelExternalId	string	No	Filter events by publishing channel external ID (example: "external123")
withTrashed	boolean	No	Include soft-deleted categories in the results (example: true)
userGroupId	string (uuid)	No	Filter categories by user group ID

Example Request

GET /api/v1/event-categories?organizationId=987e6543-e21a-34b5-c678-426614174000&limit=20&page=1&sort=name ASC&search=tech&timeRange=upcoming&userGroupId=550e8400-e29b-41d4-a716-446655440005

Response

200 OK

Returns an EventCategory object directly (note: the API returns the object itself, not a paginated wrapper).

Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Technology",
  "slug": "technology",
  "description": "Technology-related events and conferences",
  "organization": {
    "id": "987e6543-e21a-34b5-c678-426614174000",
    "name": "Tech Events Inc"
  },
  "createdAt": "2025-10-13T10:30:00.000Z",
  "updatedAt": "2025-10-13T10:30:00.000Z"
}

---

Delete Category

Deletes an event category.

HTTP Request

DELETE /api/v1/event-categories/{id}

Path Parameters

Parameter	Type	Required	Description
id	string (uuid)	Yes	The unique identifier of the category to delete

Query Parameters

Parameter	Type	Required	Description
withTrashed	boolean	No	Include trashed categories

Response

200 OK

Returns the deleted EventCategory object.

Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Technology",
  "slug": "technology",
  "description": "Technology-related events and conferences",
  "organization": {
    "id": "987e6543-e21a-34b5-c678-426614174000",
    "name": "Tech Events Inc"
  },
  "createdAt": "2025-10-13T10:30:00.000Z",
  "updatedAt": "2025-10-13T10:30:00.000Z"
}

---

EventCategory Object

The EventCategory object represents a category used to organize events.

Properties

Property	Type	Description
id	string (uuid)	The unique identifier of the category
name	string	The name of the category (max 255 characters)
slug	string	The slug for the category (URL-friendly identifier, max 255 characters)
description	string	The description of the category
organization	object	The organization associated with the event category
createdAt	string (date-time)	The date and time when the category was created
updatedAt	string (date-time)	The date and time when the category was last updated
deletedAt	string (date-time)	The deletion date of the category (if deleted)

Example

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Technology",
  "slug": "technology",
  "description": "Technology-related events and conferences",
  "organization": {
    "id": "987e6543-e21a-34b5-c678-426614174000",
    "name": "Tech Events Inc"
  },
  "createdAt": "2025-10-13T10:30:00.000Z",
  "updatedAt": "2025-10-13T10:30:00.000Z"
}