Skip to main content

​
Overview

The Events API provides endpoints to list approved events, view event details, and manage events as an organizer.

​
List All Events

curl -X GET 'https://api.example.com/api/events?page=0&size=9&search=workshop' \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/events?page=0&size=9&search=workshop
Authorization: Bearer YOUR_TOKEN
Retrieve a paginated list of all approved events. Supports search functionality.

​
Query Parameters

​
page
integer
default:"0"
Page number (zero-based pagination)
​
size
integer
default:"9"
Number of events per page
​
search
string
Search term to filter events by title or description

​
Response

​
statusCode
integer
HTTP status code (200)
​
message
string
Success message: “Events retrieved successfully”
​
data
object
Paginated event data
​
data.content
array
Array of event objects
​
data.content[].eventID
integer
Unique event identifier
​
data.content[].title
string
Event title
​
data.content[].description
string
Event description
​
data.content[].eventDate
string
Event date (ISO 8601 format: YYYY-MM-DD)
​
data.content[].startTime
string
Event start time (HH:mm:ss)
​
data.content[].endTime
string
Event end time (HH:mm:ss)
​
data.content[].venue
string
Event location/venue
​
data.content[].capacity
integer
Maximum number of participants
​
data.content[].currentRegistrations
integer
Number of current registrations
​
data.content[].status
string
Event status: UPCOMING, ONGOING, COMPLETED, CANCELLED
​
data.content[].organizationType
string
Organization type: YOUTH_UNION, STUDENT_ASSOCIATION, FACULTY, UNIVERSITY
​
data.content[].organizerID
integer
ID of the event organizer
​
data.content[].organizerName
string
Full name of the event organizer
​
data.content[].isRegistered
boolean
Whether the current user is registered for this event
​
data.content[].isOwner
boolean
Whether the current user is the organizer
​
data.pageable
object
Pagination information
​
data.totalElements
integer
Total number of events across all pages
​
data.totalPages
integer
Total number of pages
​
data.size
integer
Page size
​
data.number
integer
Current page number
{
  "statusCode": 200,
  "message": "Events retrieved successfully",
  "data": {
    "content": [
      {
        "eventID": 1,
        "title": "Spring Career Fair 2024",
        "description": "Annual career fair featuring top companies",
        "eventDate": "2024-04-15",
        "startTime": "09:00:00",
        "endTime": "17:00:00",
        "venue": "University Hall A",
        "capacity": 500,
        "currentRegistrations": 234,
        "status": "UPCOMING",
        "organizationType": "UNIVERSITY",
        "organizerID": 5,
        "organizerName": "Jane Smith",
        "isRegistered": true,
        "isOwner": false,
        "createdAt": "2024-03-01T10:00:00",
        "updatedAt": "2024-03-05T14:30:00"
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 9,
      "sort": {
        "sorted": false,
        "unsorted": true,
        "empty": true
      }
    },
    "totalElements": 25,
    "totalPages": 3,
    "size": 9,
    "number": 0
  },
  "timestamp": "2024-03-07T10:30:00"
}

​
Get Event by ID

curl -X GET https://api.example.com/api/events/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/events/{eventID}
Authorization: Bearer YOUR_TOKEN
Retrieve detailed information about a specific event.

​
Path Parameters

​
eventID
integer
required
Unique event identifier

​
Response

Returns a single EventDTO object with the same fields as the list endpoint. 
{
  "statusCode": 200,
  "message": "Event retrieved successfully",
  "data": {
    "eventID": 1,
    "title": "Spring Career Fair 2024",
    "description": "Annual career fair featuring top companies from various industries. Bring your resume and dress professionally.",
    "eventDate": "2024-04-15",
    "startTime": "09:00:00",
    "endTime": "17:00:00",
    "venue": "University Hall A",
    "capacity": 500,
    "currentRegistrations": 234,
    "status": "UPCOMING",
    "organizationType": "UNIVERSITY",
    "organizerID": 5,
    "organizerName": "Jane Smith",
    "organizationName": "Career Services Department",
    "isRegistered": true,
    "isOwner": false,
    "createdAt": "2024-03-01T10:00:00",
    "updatedAt": "2024-03-05T14:30:00"
  },
  "timestamp": "2024-03-07T10:30:00"
}

​
Error Responses

{
  "statusCode": 404,
  "message": "Event not found",
  "timestamp": "2024-03-07T10:30:00"
}

​
Get Managed Events

curl -X GET https://api.example.com/api/events/managed \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/events/managed
Authorization: Bearer YOUR_TOKEN
Retrieve all events managed by the authenticated organizer.

​
Authentication

​
Authorization
string
required
Bearer token - Requires ORGANIZER role
This endpoint requires the ORGANIZER role. The @PreAuthorize("hasRole('ORGANIZER')") annotation enforces this requirement.

​
Response

​
statusCode
integer
HTTP status code (200)
​
message
string
Success message: “Managed events retrieved successfully”
​
data
array
Array of EventDTO objects for events created by the organizer
{
  "statusCode": 200,
  "message": "Managed events retrieved successfully",
  "data": [
    {
      "eventID": 1,
      "title": "Spring Career Fair 2024",
      "description": "Annual career fair",
      "eventDate": "2024-04-15",
      "startTime": "09:00:00",
      "endTime": "17:00:00",
      "venue": "University Hall A",
      "capacity": 500,
      "currentRegistrations": 234,
      "status": "UPCOMING",
      "organizationType": "UNIVERSITY",
      "organizerID": 5,
      "organizerName": "Jane Smith",
      "isRegistered": false,
      "isOwner": true,
      "createdAt": "2024-03-01T10:00:00",
      "updatedAt": "2024-03-05T14:30:00"
    },
    {
      "eventID": 3,
      "title": "Tech Workshop Series",
      "description": "Weekly workshops on modern technologies",
      "eventDate": "2024-04-20",
      "startTime": "14:00:00",
      "endTime": "16:00:00",
      "venue": "Lab Building 201",
      "capacity": 30,
      "currentRegistrations": 28,
      "status": "UPCOMING",
      "organizationType": "FACULTY",
      "organizerID": 5,
      "organizerName": "Jane Smith",
      "isRegistered": false,
      "isOwner": true,
      "createdAt": "2024-03-10T09:00:00",
      "updatedAt": "2024-03-10T09:00:00"
    }
  ],
  "timestamp": "2024-03-07T10:30:00"
}

​
Error Responses

{
  "statusCode": 403,
  "message": "Access denied. Organizer role required.",
  "timestamp": "2024-03-07T10:30:00"
}

​
Event Status Enum

Events can have one of the following statuses:
  • UPCOMING - Event is scheduled for the future
  • ONGOING - Event is currently happening
  • COMPLETED - Event has finished
  • CANCELLED - Event has been cancelled

​
Organization Type Enum

Events are organized by different types of organizations:
  • YOUTH_UNION - Youth Union events
  • STUDENT_ASSOCIATION - Student Association events
  • FACULTY - Faculty/Department events
  • UNIVERSITY - University-wide events

Build docs developers (and LLMs) love

Get started for freeTalk to us