Admin: Events API

Overview

API for managing events. Supports destination-based and route-based events. When sending a route, provide it as GeoJSON; the API derives the encoded polyline automatically.

Authentication & Permissions

All endpoints require Auth0 authentication. Permission Model:

Regular Users: Can create, view, update, and delete their own events
Admin Users: Can create, view, update, and delete all events

List Events

GET /api/admin/events/

List events with optional filtering. Returns all events for admin users, or only the authenticated user’s events for regular users.

Query Parameters

is_active

boolean

Filter by active status

has_route

boolean

Filter events with routes

has_destination

boolean

Filter events with destinations

city

string

Filter by city name

Response

count

number

Total number of events

events

array

Array of event objects

Example

cURL

curl -X GET "https://api.cyclemate.com/api/admin/events/?is_active=true&city=New%20York" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Get Event

GET /api/admin/events/<event_id>/

Retrieve details for a specific event. Regular users can only access their own events; admins can access any event.

Path Parameters

event_id

number

required

Event ID

Response

Returns the event object with all details.

Example

cURL

curl -X GET "https://api.cyclemate.com/api/admin/events/123/" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Create Event

POST /api/admin/events/

Create a new event. Any authenticated user can create events.

Request Body

name

string

required

Event name

description

string

Event description (defaults to empty string)

emoji

string

default:"🚴"

Event emoji

image_url

string

Public URL for the event image

destination_id

number

Destination ID for destination-based events

route_geojson

object

Route geometry as a GeoJSON LineString or MultiLineString in EPSG:4326

category_ids

array

Array of category IDs

start_time

string

ISO 8601 start time (null for leisure routes)

end_time

string

ISO 8601 end time (null for leisure routes)

is_active

boolean

default:"true"

Active status

alias

string

URL-friendly alias; if omitted, generated from the name

Validation Rules

At least one of: destination_id or route_geojson must be provided.
route_geojson must be a LineString or MultiLineString in EPSG:4326.
alias must be unique across all events.

Response

Returns the created event object (201 Created).

Example

cURL

curl -X POST "https://api.cyclemate.com/api/admin/events/" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Central Park Loop",
    "description": "A scenic leisure route through Central Park",
    "emoji": "🌳",
    "route_geojson": {
      "type": "LineString",
      "coordinates": [
        [-73.9731, 40.7644],
        [-73.9712, 40.7681]
      ]
    },
    "category_ids": [4]
  }'

Update Event (Full)

PUT /api/admin/events/<event_id>/

Perform a full update of an event. All fields should be provided. Regular users can only update their own events; admins can update any event.

Path Parameters

event_id

number

required

Event ID

Request Body

Same fields as POST (Create Event), but all fields should be included for a full update.

Response

Returns the updated event object.

Example

cURL

curl -X PUT "https://api.cyclemate.com/api/admin/events/123/" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Central Park Loop",
    "description": "An updated description",
    "emoji": "🌳",
    "route_geojson": {
      "type": "LineString",
      "coordinates": [
        [-73.9731, 40.7644],
        [-73.9712, 40.7681]
      ]
    },
    "category_ids": [4],
    "is_active": true
  }'

Update Event (Partial)

PATCH /api/admin/events/<event_id>/

Perform a partial update of an event. Only include fields you want to change. Regular users can only update their own events; admins can update any event.

Path Parameters

event_id

number

required

Event ID

Request Body

Any subset of the fields from POST (Create Event). All fields are optional for PATCH.

name

string

Event name

description

string

Event description

emoji

string

Event emoji

image_url

string

Public URL for the event image

destination_id

number

Destination ID (set to null to clear)

route_geojson

object

Route geometry (set to null to clear)

category_ids

array

Array of category IDs

start_time

string

ISO 8601 start time

end_time

string

ISO 8601 end time

is_active

boolean

Active status

alias

string

URL-friendly alias (must be unique)

created_by

string

Auth0 user ID of the event owner (admin only)Admin Only: Only admin users can change the event owner. Regular users cannot modify this field.

Response

Returns the updated event object.

Example

cURL

curl -X PATCH "https://api.cyclemate.com/api/admin/events/123/" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Event Name",
    "is_active": false
  }'

Delete Event

DELETE /api/admin/events/<event_id>/

Delete an event permanently. Regular users can only delete their own events; admins can delete any event.

Path Parameters

event_id

number

required

Event ID

Response

Returns a success message (200 OK).

message

string

Confirmation message with event name

Example

cURL

curl -X DELETE "https://api.cyclemate.com/api/admin/events/123/" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Event Response Object

All endpoints that return event data include the following fields:

number

Event ID

name

string

Event name

alias

string

Event alias

description

string

Event description

emoji

string

Event emoji

image_url

string

Event image URL

start_time

string

Start time (ISO 8601) or null

end_time

string

End time (ISO 8601) or null

created_by

object

Event creator information (non-PII)

Show Creator Object

auth0_user_id

string

Auth0 user ID

name

string

User’s display name

image_url

string

User’s profile image URL

date_registered

string

User registration date

created_at

string

Created timestamp

updated_at

string

Updated timestamp

is_active

boolean

Active status

visits_total

number

Unique users who completed the event

is_leisure_route

boolean

True if permanent route with no times

city

string

City name (auto-computed from route start point). Null if no route geometry.

destination

object

DEPRECATED - Use city field instead. Destination (when applicable)

Notes

Send routes as route_geojson. The server stores geometry and derives the encoded polyline for responses.
City Auto-Computation: The city field is automatically computed from the route start point using PostGIS spatial queries. It cannot be set manually and will update whenever route_geojson changes.
All endpoints require Auth0 authentication. Regular users can only access their own events, while admin users can access all events.
When updating route_geojson, the system automatically:
- Recomputes the city field
- Regenerates event edges for routing
Setting route_geojson or destination_id to null removes the existing value.
Attempting to access another user’s event (as a non-admin) returns 403 Forbidden.
Admin-Only Feature: Admin users can change the event owner by including created_by (Auth0 user ID) in PATCH requests. Regular users cannot modify this field and will receive a 403 Forbidden error if attempted.

Admin Example: Change Event Owner

Admin users can transfer event ownership using PATCH:

cURL

curl -X PATCH "https://api.cyclemate.com/api/admin/events/123/" \
  -H "Authorization: Bearer YOUR_ADMIN_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "created_by": "google-oauth2|115315991711634062214"
  }'

This allows admins to:

Transfer event ownership between users
Reassign orphaned events
Correct ownership mistakes

Getting Started

Events

User

Users

Routing

Bikes

Admin

Overview

Authentication & Permissions

List Events

Query Parameters

Response

Example

Get Event

Path Parameters

Response

Example

Create Event

Request Body

Validation Rules

Response

Example

Update Event (Full)

Path Parameters

Request Body

Response

Example

Update Event (Partial)

Path Parameters

Request Body

Response

Example

Delete Event

Path Parameters

Response

Example

Event Response Object

Notes

Admin Example: Change Event Owner

Getting Started

Events

User

Users

Routing

Bikes

Admin

​Overview

​Authentication & Permissions

​List Events

​Query Parameters

​Response

​Example

​Get Event

​Path Parameters

​Response

​Example

​Create Event

​Request Body

​Validation Rules

​Response

​Example

​Update Event (Full)

​Path Parameters

​Request Body

​Response

​Example

​Update Event (Partial)

​Path Parameters

​Request Body

​Response

​Example

​Delete Event

​Path Parameters

​Response

​Example

​Event Response Object

​Notes

​Admin Example: Change Event Owner

Overview

Authentication & Permissions

List Events

Query Parameters

Response

Example

Get Event

Path Parameters

Response

Example

Create Event

Request Body

Validation Rules

Response

Example

Update Event (Full)

Path Parameters

Request Body

Response

Example

Update Event (Partial)

Path Parameters

Request Body

Response

Example

Delete Event

Path Parameters

Response

Example

Event Response Object

Notes

Admin Example: Change Event Owner