> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/devcarlosperez/EcoEvents/llms.txt
> Use this file to discover all available pages before exploring further.

# Events API

> Manage sustainable events with full CRUD operations

## 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:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

***

## Create Event

<Card title="POST /api/events" icon="plus">
  Create a new sustainable event with carbon tracking and eco-friendly options.
</Card>

### Request

<ParamField path="name" type="string" required>
  The name of the event
</ParamField>

<ParamField path="description" type="string">
  A detailed description of the event
</ParamField>

<ParamField path="location" type="object" required>
  Event location details

  <Expandable title="properties">
    <ParamField path="address" type="string" required>
      Street address of the venue
    </ParamField>

    <ParamField path="city" type="string" required>
      City name
    </ParamField>

    <ParamField path="state" type="string">
      State or province
    </ParamField>

    <ParamField path="country" type="string" required>
      Country code (ISO 3166-1 alpha-2)
    </ParamField>

    <ParamField path="zipCode" type="string">
      Postal code
    </ParamField>

    <ParamField path="coordinates" type="object">
      Geographic coordinates

      <Expandable title="properties">
        <ParamField path="lat" type="number">
          Latitude
        </ParamField>

        <ParamField path="lng" type="number">
          Longitude
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="startDate" type="string" required>
  Event start date and time (ISO 8601 format)
</ParamField>

<ParamField path="endDate" type="string" required>
  Event end date and time (ISO 8601 format)
</ParamField>

<ParamField path="capacity" type="integer" required>
  Maximum number of attendees
</ParamField>

<ParamField path="category" type="string" required>
  Event category (e.g., "conference", "workshop", "festival", "meetup")
</ParamField>

<ParamField path="sustainabilityGoals" type="object">
  Sustainability targets for the event

  <Expandable title="properties">
    <ParamField path="carbonNeutral" type="boolean">
      Target carbon neutral status
    </ParamField>

    <ParamField path="wasteReduction" type="number">
      Target waste reduction percentage
    </ParamField>

    <ParamField path="localSourcing" type="boolean">
      Use locally sourced materials and vendors
    </ParamField>

    <ParamField path="renewableEnergy" type="boolean">
      Use renewable energy sources
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="tags" type="array">
  Array of tags for categorization
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique identifier for the event
</ResponseField>

<ResponseField name="name" type="string">
  The name of the event
</ResponseField>

<ResponseField name="description" type="string">
  Event description
</ResponseField>

<ResponseField name="location" type="object">
  Event location details

  <Expandable title="properties">
    <ResponseField name="address" type="string">
      Street address
    </ResponseField>

    <ResponseField name="city" type="string">
      City name
    </ResponseField>

    <ResponseField name="state" type="string">
      State or province
    </ResponseField>

    <ResponseField name="country" type="string">
      Country code
    </ResponseField>

    <ResponseField name="zipCode" type="string">
      Postal code
    </ResponseField>

    <ResponseField name="coordinates" type="object">
      Geographic coordinates
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="startDate" type="string">
  Event start date and time
</ResponseField>

<ResponseField name="endDate" type="string">
  Event end date and time
</ResponseField>

<ResponseField name="capacity" type="integer">
  Maximum attendee capacity
</ResponseField>

<ResponseField name="category" type="string">
  Event category
</ResponseField>

<ResponseField name="sustainabilityGoals" type="object">
  Sustainability targets
</ResponseField>

<ResponseField name="tags" type="array">
  Event tags
</ResponseField>

<ResponseField name="status" type="string">
  Event status ("draft", "published", "cancelled", "completed")
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp when the event was created
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Timestamp when the event was last updated
</ResponseField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "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

<Card title="GET /api/events/:id" icon="eye">
  Retrieve a specific event by ID.
</Card>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the event
</ParamField>

### Response

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

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.ecoevents.com/api/events/evt_1a2b3c4d5e6f \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

***

## Update Event

<Card title="PUT /api/events/:id" icon="pen-to-square">
  Update an existing event. All fields are optional.
</Card>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the event to update
</ParamField>

### Request

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

<ParamField path="name" type="string">
  Updated event name
</ParamField>

<ParamField path="description" type="string">
  Updated event description
</ParamField>

<ParamField path="location" type="object">
  Updated location details
</ParamField>

<ParamField path="startDate" type="string">
  Updated start date and time
</ParamField>

<ParamField path="endDate" type="string">
  Updated end date and time
</ParamField>

<ParamField path="capacity" type="integer">
  Updated capacity
</ParamField>

<ParamField path="category" type="string">
  Updated category
</ParamField>

<ParamField path="sustainabilityGoals" type="object">
  Updated sustainability goals
</ParamField>

<ParamField path="tags" type="array">
  Updated tags
</ParamField>

<ParamField path="status" type="string">
  Updated status ("draft", "published", "cancelled", "completed")
</ParamField>

### Response

Returns the updated event object.

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

***

## Delete Event

<Card title="DELETE /api/events/:id" icon="trash">
  Permanently delete an event. This action cannot be undone.
</Card>

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the event to delete
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates whether the deletion was successful
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message
</ResponseField>

<ResponseField name="deletedId" type="string">
  The ID of the deleted event
</ResponseField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.ecoevents.com/api/events/evt_1a2b3c4d5e6f \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "success": true,
  "message": "Event successfully deleted",
  "deletedId": "evt_1a2b3c4d5e6f"
}
```

***

## List Events

<Card title="GET /api/events" icon="list">
  Retrieve a paginated list of events with optional filtering.
</Card>

### Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of events per page (max 100)
</ParamField>

<ParamField query="status" type="string">
  Filter by event status ("draft", "published", "cancelled", "completed")
</ParamField>

<ParamField query="category" type="string">
  Filter by event category
</ParamField>

<ParamField query="startDate" type="string">
  Filter events starting after this date (ISO 8601)
</ParamField>

<ParamField query="endDate" type="string">
  Filter events ending before this date (ISO 8601)
</ParamField>

<ParamField query="search" type="string">
  Search events by name or description
</ParamField>

<ParamField query="tags" type="string">
  Comma-separated list of tags to filter by
</ParamField>

<ParamField query="sortBy" type="string" default="createdAt">
  Field to sort by ("createdAt", "startDate", "name", "capacity")
</ParamField>

<ParamField query="order" type="string" default="desc">
  Sort order ("asc" or "desc")
</ParamField>

### Response

<ResponseField name="events" type="array">
  Array of event objects
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination information

  <Expandable title="properties">
    <ResponseField name="page" type="integer">
      Current page number
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Events per page
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of events
    </ResponseField>

    <ResponseField name="totalPages" type="integer">
      Total number of pages
    </ResponseField>

    <ResponseField name="hasNext" type="boolean">
      Whether there is a next page
    </ResponseField>

    <ResponseField name="hasPrev" type="boolean">
      Whether there is a previous page
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.ecoevents.com/api/events?page=1&limit=10&status=published&category=conference" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "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:

<ResponseField name="error" type="object">
  Error details

  <Expandable title="properties">
    <ResponseField name="code" type="string">
      Error code (e.g., "INVALID\_REQUEST", "NOT\_FOUND", "UNAUTHORIZED")
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error message
    </ResponseField>

    <ResponseField name="details" type="object">
      Additional error context (optional)
    </ResponseField>
  </Expandable>
</ResponseField>

### 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                       |