Events API — CRUD Endpoints and Conflict Detection

The Events API is the core of UniEvents. Each event belongs to a faculty tenant and is bound to a physical space. Before an event is persisted, the service layer runs an overlap check — if another event already occupies the same space during the requested time window, the request is rejected with a CONF_001 conflict error. Images are uploaded to Supabase storage, compressed to WebP via Sharp, and the resulting URL is stored alongside the event record.

GET /api/events

Returns all events that belong to a given tenant, ordered by creation date (newest first). Each event in the response includes the related space object. Authentication: Not required.

tenantId

string

required

The UUID of the tenant (faculty) whose events you want to retrieve. Returns 400 if omitted.

curl "https://your-domain.com/api/events?tenantId=a1b2c3d4-e5f6-7890-abcd-ef1234567890"

200 Response

[
  {
    "id": "evt_uuid",
    "title": "Congreso de Ingeniería 2025",
    "slug": "congreso-de-ingenieria-2025",
    "description": "Evento anual de la facultad de ingeniería.",
    "date": "2025-09-15T09:00:00.000Z",
    "price": "0.00",
    "imageUrl": "https://cdn.supabase.io/storage/v1/object/public/events/event-1234567890.webp",
    "duration": 120,
    "tenantId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "spaceId": "sp_uuid",
    "capacity": 200,
    "visibility": "publico",
    "status": "aprobado",
    "requiresIpProtection": false,
    "isFeatured": false,
    "paymentPhone": null,
    "paymentId": null,
    "paymentBank": null,
    "managerId": "usr_uuid",
    "createdAt": "2025-08-01T14:22:00.000Z",
    "space": {
      "id": "sp_uuid",
      "name": "Auditorio Principal",
      "capacity": 300,
      "tenantId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "createdAt": "2025-01-10T10:00:00.000Z"
    }
  }
]

string

UUID of the event.

title

string

Display title of the event.

slug

string

URL-safe unique identifier auto-generated from the title.

description

string | null

Optional longer description of the event.

date

string (ISO 8601)

Start date and time of the event in UTC.

price

string (decimal)

Ticket price. Defaults to "0.00" for free events.

imageUrl

string | null

Supabase public URL for the event cover image (WebP).

duration

integer

Duration in minutes. Defaults to 60.

tenantId

string

UUID of the owning tenant (faculty).

spaceId

string

UUID of the reserved venue space.

capacity

integer | null

Maximum number of attendees. null means unlimited.

visibility

"publico" | "privado"

Whether the event is publicly listed or restricted.

status

"pendiente" | "aprobado" | "rechazado"

Approval status. Events created by event_manager users start as "pendiente"; tenant_admin and superadmin events default to "aprobado".

requiresIpProtection

boolean

If true, access to the event is restricted by IP.

isFeatured

boolean

Whether the event is highlighted on the tenant’s public page.

paymentPhone

string | null

Mobile payment phone number (for mobile transfer payments).

paymentId

string | null

Payment account identifier.

paymentBank

string | null

Bank name for payment instructions.

managerId

string

UUID of the user responsible for managing this event.

createdAt

string (ISO 8601)

Timestamp when the record was created.

space

object

Related space object. See the Spaces schema for field details.

POST /api/events

Creates a new event. The request must be sent as multipart/form-data to support optional image upload. The service checks for scheduling conflicts in the target space before inserting the record. A unique slug is generated automatically from the title. Authentication: Required (session cookie). Returns 401 if no valid session is present. Content-Type: multipart/form-data

title

string

required

Display title for the event.

tenantId

string

required

UUID of the tenant (faculty) that owns this event.

spaceId

string

required

UUID of the space where the event will be held. Used for conflict detection.

date

string

required

ISO 8601 date-time string for the event start time (e.g. "2025-09-15T09:00:00.000Z").

managerId

string

required

UUID of the user who will manage this event. Returns 400 if omitted.

description

string

Optional description of the event.

duration

integer

Duration in minutes. Defaults to 60 if not provided.

price

string

Ticket price as a decimal string (e.g. "15.00"). Defaults to "0".

capacity

integer

Maximum attendee count. Omit or leave blank for no cap.

visibility

"publico" | "privado"

Listing visibility. Defaults to "publico".

requiresIpProtection

"true" | "false"

String boolean. Set to "true" to enable IP-based access restriction.

image

File

Optional cover image. Accepted formats: image/jpeg, image/png, image/webp. Maximum size: 5 MB. The image is resized to 1200×800, converted to WebP at 80% quality, and uploaded to Supabase storage.

paymentPhone

string

Phone number for mobile transfer payment instructions.

paymentId

string

Account ID for payment instructions.

paymentBank

string

Bank name for payment instructions.

curl -X POST "https://your-domain.com/api/events" \
  -H "Cookie: session=<your-session-token>" \
  -F "title=Congreso de Ingeniería 2025" \
  -F "date=2025-09-15T09:00:00.000Z" \
  -F "duration=120" \
  -F "tenantId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -F "spaceId=sp_uuid" \
  -F "managerId=usr_uuid" \
  -F "visibility=publico" \
  -F "price=0" \
  -F "image=@/path/to/cover.jpg"

201 Response — Returns the newly created event object (same shape as the GET response above). Error Responses

Status	Code	Description
`400`	—	Missing required field (`title`, `date`, `tenantId`, `spaceId`, or `managerId`).
`400`	—	Image exceeds 5 MB or is an unsupported format.
`401`	—	No valid session cookie present.
`409`	`CONF_001`	The requested space is already booked during the specified time window.

{ "error": "CONF_001: El espacio ya está reservado para esa fecha y hora." }

GET /api/events/{id}

Returns a single event by its UUID, including the related space object. Authentication: Not required.

string

required

UUID of the event to retrieve.

curl "https://your-domain.com/api/events/evt_uuid"

200 Response — A single event object with the same fields as the list response above. 404 Response

{ "error": "Not found" }

PUT /api/events/{id}

Updates an existing event. Accepts either multipart/form-data (to replace the cover image) or application/json (for field-only updates). All fields are optional — only provided fields are updated. If spaceId, date, or duration is included in the update payload, the conflict check runs again (excluding the current event from the comparison). Authentication: Required (session cookie). Returns 401 if no valid session is present.

string

required

UUID of the event to update.

title

string

Updated title. Triggers slug regeneration.

description

string

Updated description.

date

string

New start date-time (ISO 8601). Triggers conflict check.

duration

integer

New duration in minutes. Triggers conflict check.

price

string

Updated ticket price.

spaceId

string

New space UUID. Triggers conflict check.

capacity

integer

Updated attendee cap.

visibility

"publico" | "privado"

Updated visibility setting.

status

"pendiente" | "aprobado" | "rechazado"

Updated approval status.

requiresIpProtection

boolean

Updated IP protection flag.

managerId

string

UUID of the new manager.

paymentPhone

string

Updated payment phone.

paymentId

string

Updated payment account ID.

paymentBank

string

Updated payment bank name.

image

File

Replacement cover image (multipart/form-data only). Same size and format rules as POST.

# JSON update (no image change)
curl -X PUT "https://your-domain.com/api/events/evt_uuid" \
  -H "Cookie: session=<your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "aprobado", "capacity": 250}'

200 Response — The updated event object. Error Responses

Status	Code	Description
`401`	—	No valid session cookie.
`409`	`CONF_001`	Space conflict detected after applying the new `spaceId`, `date`, or `duration`.

DELETE /api/events/{id}

Permanently deletes an event by its UUID. Authentication: Required (session cookie). Returns 401 if no valid session is present.

string

required

UUID of the event to delete.

curl -X DELETE "https://your-domain.com/api/events/evt_uuid" \
  -H "Cookie: session=<your-session-token>"

204 Response — No content. Deletion was successful. Error Responses

Status	Description
`401`	No valid session cookie present.

Authentication

Resources

Events API — CRUD Endpoints and Conflict Detection

GET /api/events

POST /api/events

GET /api/events/{id}

PUT /api/events/{id}

DELETE /api/events/{id}

Build docs developers (and LLMs) love

Authentication

Resources

Documentation Index

​GET /api/events

​POST /api/events

​GET /api/events/{id}

​PUT /api/events/{id}

​DELETE /api/events/{id}

Build docs developers (and LLMs) love

GET /api/events

POST /api/events

GET /api/events/{id}

PUT /api/events/{id}

DELETE /api/events/{id}