Back to eventsPublic API v1

API guide.

List our events on your site. No key required — link each card back to its url.

Try it live
01

Overview

Base URLhttps://event.ieeecsseu.org
Versionv1 — URL-versioned. Breaking changes ship as a new version, never in place.
AuthNone — unauthenticated, read-only. GET only.
Spec/api/v1/openapi.json — import into Postman or Insomnia.
02

Conventions

Every endpoint follows these rules — once you know one, you know them all.

ConventionRule
Collections{ data[], meta }
Single resource{ data }
Errors{ error, code }
Paginationpage · limit + meta.totalPages
DatesISO-8601, null means TBA
03

Endpoints

GET/api/v1/events

Paginated event list. Filter by lifecycle status. status=all returns running, then upcoming, then completed — latest start date first within each group (TBA last).

ParamValuesDefault
statusupcoming · running · completed · allall
page1–10001
limit1–10020
cURL
curl "https://event.ieeecsseu.org/api/v1/events?status=upcoming&limit=5"
GET/api/v1/events/:slug

One event. :slug is the last segment of its url. Unknown, draft, and archived slugs all return 404. Same 9 fields as the list, without meta.

cURL
curl "https://event.ieeecsseu.org/api/v1/events/robo-fest-2026"
04

Schema

Every event returns exactly these 9 fields — nothing more.

FieldType
urlEventOS link — link to this
titlestring
statePUBLISHED · RUNNING · COMPLETED
startDatestring | null
endDatestring | null
venueInfostring | null
coverImageUrlstring | null
categorystring
tagsstring[]
05

Errors

CodeMeaning
400Invalid parameters
404Event not found
405Only GET is allowed
429Too many requests — wait and retry

Fair-use limits apply. Please cache responses on your side.

06

Use AI

Paste this prompt into any AI assistant and it will integrate the API into your project.

AI prompt
Please integrate the EventOS Public API v1 with the existing events area/section of my website, acting as a senior integration engineer and writing clean, production-quality code.

## Background

EventOS publishes events run by IEEE CS SEU. Its public API is a free, read-only, referral-only feed: I want to list these events on my own site, with every card linking back to the event page on EventOS. No API key is required, and only GET requests are supported.

- Base URL: https://event.ieeecsseu.org
- Machine-readable OpenAPI spec: https://event.ieeecsseu.org/api/v1/openapi.json

## Endpoints

| Method | Endpoint | Description |
| ------ | -------- | ----------- |
| GET | /api/v1/events | Paginated event list, filterable by status |
| GET | /api/v1/events/:slug | A single event, where :slug is the last segment of its "url" |

Query parameters for the list endpoint:

| Parameter | Allowed values | Default |
| --------- | -------------- | ------- |
| status | upcoming, running, completed, all | all |
| page | integer, 1 to 1000 | 1 |
| limit | integer, 1 to 100 | 20 |

Status mapping: upcoming means PUBLISHED events, running means RUNNING, and completed means COMPLETED only. Draft and archived events are never listed, and the detail endpoint returns 404 for them exactly as it does for an unknown slug. Ordering: status=all returns running first, then upcoming, then completed (latest startDate first within each group, null last).

## Response format

A collection returns an object with a "data" array and a "meta" object:

```json
{ "data": [Event], "meta": { "status": "running", "page": 1, "limit": 10, "total": 3, "totalPages": 1 } }
```

A single event returns `{ "data": Event }`, and every error returns `{ "error": "<message>", "code": "<ERROR_CODE>" }`.

Each event carries exactly these 9 fields and nothing more:

```json
{
  "url": "https://event.ieeecsseu.org/events/robo-fest-2026",
  "title": "Robo Fest 2026",
  "state": "RUNNING",
  "startDate": "2026-03-10T04:00:00.000Z",
  "endDate": null,
  "venueInfo": "SEU Campus, Dhaka",
  "coverImageUrl": "https://event.ieeecsseu.org/icon-512.png",
  "category": "COMPETITION",
  "tags": ["robotics"]
}
```

"state" is one of PUBLISHED, RUNNING, or COMPLETED. Dates are ISO-8601 strings, or null when to be announced. "coverImageUrl" is an absolute URL that is safe to hotlink, though it may be a placeholder image.

## Integration requirements

1. Every rendered card must link to its "url", opening in a new tab with rel="noopener".
2. Null dates must be displayed as "TBA" — never render a raw null.
3. Always provide an image alt fallback in case the cover is a placeholder.
4. Cache responses on the client and poll the API at a gentle cadence.
5. Handle failures gracefully: 400 means the request parameters need fixing, 404 means the event should be hidden or skipped, and 429 means wait and retry with backoff.
6. Match my existing events area's current design, styling, and markup conventions — do not introduce a new look, page, or project.

## Your task

Wire this API into my EXISTING events area/section — not a new page and not a new project. Before writing code, please ask me for:
1. How my current events area is built (my stack, plus the relevant existing code for that section).
2. Which status filter and page size I want to show there.
3. Whether the API events should replace my current static events, merge with them, or appear as a separate block within the section.

Then deliver the minimum complete changes to my existing code.

## How to present your answer

- One section per existing file I need to touch, with its exact path, showing precisely what to add, remove, or change.
- Follow with numbered setup steps, and finally how I can verify the result (which URL to open and what I should see).

Acceptance criteria: my existing events area renders the live API events (cover, title, date range, venue, category, and tags) while keeping its current design; loading, empty, and error states handled; no hardcoded event data — everything comes from the live API.