Events API

Overview

The Events API allows you to create, retrieve, update, and delete events in your EcoEvents platform. All endpoints require authentication via API key.

Authentication

All API requests require an API key to be included in the header:

Authorization: Bearer YOUR_API_KEY

Create Event

POST /api/events

Create a new sustainable event with carbon tracking and eco-friendly options.

Request

name

string

required

The name of the event

description

string

A detailed description of the event

location

object

required

Event location details

Show properties

address

string

required

Street address of the venue

city

string

required

City name

state

string

State or province

country

string

required

Country code (ISO 3166-1 alpha-2)

zipCode

string

Postal code

coordinates

object

Geographic coordinates

Show properties

lat

number

Latitude

lng

number

Longitude

startDate

string

required

Event start date and time (ISO 8601 format)

endDate

string

required

Event end date and time (ISO 8601 format)

capacity

integer

required

Maximum number of attendees

category

string

required

Event category (e.g., “conference”, “workshop”, “festival”, “meetup”)

sustainabilityGoals

object

Sustainability targets for the event

Show properties

carbonNeutral

boolean

Target carbon neutral status

wasteReduction

number

Target waste reduction percentage

localSourcing

boolean

Use locally sourced materials and vendors

renewableEnergy

boolean

Use renewable energy sources

tags

array

Array of tags for categorization

Response

string

Unique identifier for the event

name

string

The name of the event

description

string

Event description

location

object

Event location details

Show properties

address

string

Street address

city

string

City name

state

string

State or province

country

string

Country code

zipCode

string

Postal code

coordinates

object

Geographic coordinates

startDate

string

Event start date and time

endDate

string

Event end date and time

capacity

integer

Maximum attendee capacity

category

string

Event category

sustainabilityGoals

object

Sustainability targets

tags

array

Event tags

status

string

Event status (“draft”, “published”, “cancelled”, “completed”)

createdAt

string

Timestamp when the event was created

updatedAt

string

Timestamp when the event was last updated

Example

curl -X POST https://api.ecoevents.com/api/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sustainable Tech Summit 2026",
    "description": "A conference focused on sustainable technology solutions",
    "location": {
      "address": "123 Green Street",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "zipCode": "94102",
      "coordinates": {
        "lat": 37.7749,
        "lng": -122.4194
      }
    },
    "startDate": "2026-06-15T09:00:00Z",
    "endDate": "2026-06-17T18:00:00Z",
    "capacity": 500,
    "category": "conference",
    "sustainabilityGoals": {
      "carbonNeutral": true,
      "wasteReduction": 80,
      "localSourcing": true,
      "renewableEnergy": true
    },
    "tags": ["technology", "sustainability", "green-tech"]
  }'

Response Example

{
  "id": "evt_1a2b3c4d5e6f",
  "name": "Sustainable Tech Summit 2026",
  "description": "A conference focused on sustainable technology solutions",
  "location": {
    "address": "123 Green Street",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "zipCode": "94102",
    "coordinates": {
      "lat": 37.7749,
      "lng": -122.4194
    }
  },
  "startDate": "2026-06-15T09:00:00Z",
  "endDate": "2026-06-17T18:00:00Z",
  "capacity": 500,
  "category": "conference",
  "sustainabilityGoals": {
    "carbonNeutral": true,
    "wasteReduction": 80,
    "localSourcing": true,
    "renewableEnergy": true
  },
  "tags": ["technology", "sustainability", "green-tech"],
  "status": "draft",
  "createdAt": "2026-03-05T10:30:00Z",
  "updatedAt": "2026-03-05T10:30:00Z"
}

Get Event

GET /api/events/:id

Retrieve a specific event by ID.

Path Parameters

string

required

The unique identifier of the event

Response

Returns the same event object structure as the Create Event endpoint.

Example

curl -X GET https://api.ecoevents.com/api/events/evt_1a2b3c4d5e6f \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Event

PUT /api/events/:id

Update an existing event. All fields are optional.

Path Parameters

string

required

The unique identifier of the event to update

Request

Accepts the same parameters as Create Event, but all fields are optional. Only include fields you want to update.

name

string

Updated event name

description

string

Updated event description

location

object

Updated location details

startDate

string

Updated start date and time

endDate

string

Updated end date and time

capacity

integer

Updated capacity

category

string

Updated category

sustainabilityGoals

object

Updated sustainability goals

tags

array

Updated tags

status

string

Updated status (“draft”, “published”, “cancelled”, “completed”)

Response

Returns the updated event object.

Example

curl -X PUT https://api.ecoevents.com/api/events/evt_1a2b3c4d5e6f \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "capacity": 600,
    "status": "published"
  }'

Delete Event

DELETE /api/events/:id

Permanently delete an event. This action cannot be undone.

Path Parameters

string

required

The unique identifier of the event to delete

Response

success

boolean

Indicates whether the deletion was successful

message

string

Confirmation message

deletedId

string

The ID of the deleted event

Example

curl -X DELETE https://api.ecoevents.com/api/events/evt_1a2b3c4d5e6f \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "message": "Event successfully deleted",
  "deletedId": "evt_1a2b3c4d5e6f"
}

List Events

GET /api/events

Retrieve a paginated list of events with optional filtering.

Query Parameters

page

integer

default:"1"

Page number for pagination

limit

integer

default:"20"

Number of events per page (max 100)

status

string

Filter by event status (“draft”, “published”, “cancelled”, “completed”)

category

string

Filter by event category

startDate

string

Filter events starting after this date (ISO 8601)

endDate

string

Filter events ending before this date (ISO 8601)

string

Search events by name or description

tags

string

Comma-separated list of tags to filter by

sortBy

string

default:"createdAt"

Field to sort by (“createdAt”, “startDate”, “name”, “capacity”)

order

string

default:"desc"

Sort order (“asc” or “desc”)

Response

events

array

Array of event objects

pagination

object

Pagination information

Show properties

page

integer

Current page number

limit

integer

Events per page

total

integer

Total number of events

totalPages

integer

Total number of pages

hasNext

boolean

Whether there is a next page

hasPrev

boolean

Whether there is a previous page

Example

curl -X GET "https://api.ecoevents.com/api/events?page=1&limit=10&status=published&category=conference" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "events": [
    {
      "id": "evt_1a2b3c4d5e6f",
      "name": "Sustainable Tech Summit 2026",
      "description": "A conference focused on sustainable technology solutions",
      "location": {
        "city": "San Francisco",
        "country": "US"
      },
      "startDate": "2026-06-15T09:00:00Z",
      "endDate": "2026-06-17T18:00:00Z",
      "capacity": 600,
      "category": "conference",
      "status": "published"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Error Responses

All endpoints may return the following error responses:

error

object

Error details

Show properties

code

string

Error code (e.g., “INVALID_REQUEST”, “NOT_FOUND”, “UNAUTHORIZED”)

message

string

Human-readable error message

details

object

Additional error context (optional)

Common Error Codes

Status Code	Error Code	Description
400	INVALID_REQUEST	Invalid request parameters or body
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Insufficient permissions
404	NOT_FOUND	Event not found
429	RATE_LIMIT_EXCEEDED	Too many requests
500	INTERNAL_ERROR	Server error

Overview

Endpoints

Overview

Authentication

Create Event

POST /api/events

Request

Response

Example

Response Example

Get Event

GET /api/events/:id

Path Parameters

Response

Example

Update Event

PUT /api/events/:id

Path Parameters

Request

Response

Example

Delete Event

DELETE /api/events/:id

Path Parameters

Response

Example

Response Example

List Events

GET /api/events

Query Parameters

Response

Example

Response Example

Error Responses

Common Error Codes

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​Authentication

​Create Event

POST /api/events

​Request

​Response

​Example

​Response Example

​Get Event

GET /api/events/:id

​Path Parameters

​Response

​Example

​Update Event

PUT /api/events/:id

​Path Parameters

​Request

​Response

​Example

​Delete Event

DELETE /api/events/:id

​Path Parameters

​Response

​Example

​Response Example

​List Events

GET /api/events

​Query Parameters

​Response

​Example

​Response Example

​Error Responses

​Common Error Codes

Build docs developers (and LLMs) love

Overview

Authentication

Create Event

Request

Response

Example

Response Example

Get Event

Path Parameters

Response

Example

Update Event

Path Parameters

Request

Response

Example

Delete Event

Path Parameters

Response

Example

Response Example

List Events

Query Parameters

Response

Example

Response Example

Error Responses

Common Error Codes