Events API - EcoEvents

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

string

required

The name of the event

string

A detailed description of the event

object

required

Event location details

Show properties

string

required

Street address of the venue

string

required

City name

string

State or province

string

required

Country code (ISO 3166-1 alpha-2)

string

Postal code

object

Geographic coordinates

Show properties

number

Latitude

number

Longitude

string

required

Event start date and time (ISO 8601 format)

string

required

Event end date and time (ISO 8601 format)

integer

required

Maximum number of attendees

string

required

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

object

Sustainability targets for the event

Show properties

boolean

Target carbon neutral status

number

Target waste reduction percentage

boolean

Use locally sourced materials and vendors

boolean

Use renewable energy sources

array

Array of tags for categorization

Response

string

Unique identifier for the event

string

The name of the event

string

Event description

object

Event location details

Show properties

string

Street address

string

City name

string

State or province

string

Country code

string

Postal code

object

Geographic coordinates

string

Event start date and time

string

Event end date and time

integer

Maximum attendee capacity

string

Event category

object

Sustainability targets

array

Event tags

string

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

string

Timestamp when the event was created

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"]
  }'

const response = await fetch('https://api.ecoevents.com/api/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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']
  })
});

const event = await response.json();
console.log(event);

import requests

url = 'https://api.ecoevents.com/api/events'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    '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 = requests.post(url, headers=headers, json=data)
event = response.json()
print(event)

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"

const response = await fetch('https://api.ecoevents.com/api/events/evt_1a2b3c4d5e6f', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const event = await response.json();
console.log(event);

import requests

url = 'https://api.ecoevents.com/api/events/evt_1a2b3c4d5e6f'
headers = {'Authorization': 'Bearer YOUR_API_KEY'}

response = requests.get(url, headers=headers)
event = response.json()
print(event)

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.

string

Updated event name

string

Updated event description

object

Updated location details

string

Updated start date and time

string

Updated end date and time

integer

Updated capacity

string

Updated category

object

Updated sustainability goals

array

Updated tags

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"
  }'

const response = await fetch('https://api.ecoevents.com/api/events/evt_1a2b3c4d5e6f', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    capacity: 600,
    status: 'published'
  })
});

const updatedEvent = await response.json();
console.log(updatedEvent);

import requests

url = 'https://api.ecoevents.com/api/events/evt_1a2b3c4d5e6f'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'capacity': 600,
    'status': 'published'
}

response = requests.put(url, headers=headers, json=data)
updated_event = response.json()
print(updated_event)

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

boolean

Indicates whether the deletion was successful

string

Confirmation message

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"

const response = await fetch('https://api.ecoevents.com/api/events/evt_1a2b3c4d5e6f', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const result = await response.json();
console.log(result);

import requests

url = 'https://api.ecoevents.com/api/events/evt_1a2b3c4d5e6f'
headers = {'Authorization': 'Bearer YOUR_API_KEY'}

response = requests.delete(url, headers=headers)
result = response.json()
print(result)

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

integer

default:"1"

Page number for pagination

integer

default:"20"

Number of events per page (max 100)

string

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

string

Filter by event category

string

Filter events starting after this date (ISO 8601)

string

Filter events ending before this date (ISO 8601)

string

Search events by name or description

string

Comma-separated list of tags to filter by

string

default:"createdAt"

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

string

default:"desc"

Sort order (“asc” or “desc”)

Response

array

Array of event objects

object

Pagination information

Show properties

integer

Current page number

integer

Events per page

integer

Total number of events

integer

Total number of pages

boolean

Whether there is a next page

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"

const params = new URLSearchParams({
  page: '1',
  limit: '10',
  status: 'published',
  category: 'conference'
});

const response = await fetch(`https://api.ecoevents.com/api/events?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

import requests

url = 'https://api.ecoevents.com/api/events'
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
params = {
    'page': 1,
    'limit': 10,
    'status': 'published',
    'category': 'conference'
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)

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:

object

Error details

Show properties

string

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

string

Human-readable error message

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

​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

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