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

# Events API

> Retrieve upcoming and past events in Dzaleka Refugee Camp

## GET /api/events

Retrieve a list of all events in Dzaleka Refugee Camp.

### Query Parameters

This endpoint does not require any query parameters.

### Response Format

<ResponseField name="status" type="string" required>
  Status of the API response ("success" or "error")
</ResponseField>

<ResponseField name="count" type="number" required>
  Total number of events returned
</ResponseField>

<ResponseField name="data" type="object" required>
  Container for the events data

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

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

    <ResponseField name="collection" type="string">
      Collection name ("events")
    </ResponseField>

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

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

    <ResponseField name="date" type="string">
      Event start date and time (ISO 8601 format)
    </ResponseField>

    <ResponseField name="endDate" type="string">
      Event end date (YYYY-MM-DD)
    </ResponseField>

    <ResponseField name="location" type="string">
      Event location (e.g., "Online", "Dzaleka Community Center")
    </ResponseField>

    <ResponseField name="category" type="string">
      Event category (e.g., "Zoom Meeting", "Workshop", "Conference")
    </ResponseField>

    <ResponseField name="image" type="string">
      URL to event image
    </ResponseField>

    <ResponseField name="featured" type="boolean">
      Whether the event is featured
    </ResponseField>

    <ResponseField name="organizer" type="string">
      Name of the organizing entity
    </ResponseField>

    <ResponseField name="status" type="string">
      Event status ("upcoming", "ongoing", "past")
    </ResponseField>

    <ResponseField name="contact" type="object">
      Contact information

      <ResponseField name="email" type="string">
        Contact email
      </ResponseField>

      <ResponseField name="phone" type="string">
        Contact phone number
      </ResponseField>

      <ResponseField name="whatsapp" type="string">
        WhatsApp number
      </ResponseField>
    </ResponseField>

    <ResponseField name="registration" type="object">
      Registration details

      <ResponseField name="required" type="boolean">
        Whether registration is required
      </ResponseField>

      <ResponseField name="url" type="string">
        Registration URL
      </ResponseField>

      <ResponseField name="deadline" type="string">
        Registration deadline (YYYY-MM-DD)
      </ResponseField>
    </ResponseField>

    <ResponseField name="tags" type="array">
      Array of tag strings
    </ResponseField>
  </ResponseField>
</ResponseField>

### Error Responses

<ResponseField name="status" type="string">
  "error"
</ResponseField>

<ResponseField name="message" type="string">
  Error message description
</ResponseField>

<ResponseField name="error" type="string">
  Detailed error information
</ResponseField>

**Status Codes:**

* `200` - Success
* `429` - Rate limit exceeded (60 requests per minute)
* `500` - Internal server error

### Rate Limiting

All API endpoints are rate-limited to 60 requests per minute per IP address. Rate limit headers are included in responses:

* `X-RateLimit-Limit`: Maximum requests per window
* `X-RateLimit-Remaining`: Remaining requests in current window
* `X-RateLimit-Reset`: Timestamp when the rate limit resets
* `Retry-After`: Seconds to wait before retrying (only on 429 responses)

### Example Request

```bash theme={null}
curl -X GET "https://services.dzaleka.com/api/events" \
  -H "Content-Type: application/json"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "count": 1,
  "data": {
    "events": [
      {
        "id": "Breaking Myths About Refugees",
        "collection": "events",
        "title": "Breaking Myths About Refugees: Truths That Change Perceptions",
        "description": "Refugees and migrants face misconceptions worldwide, but in this session, we focus on Malawi and the broader sub-Saharan Africa region.",
        "date": "2025-04-24T13:00:00.000Z",
        "endDate": "2025-04-24",
        "location": "Online",
        "category": "Zoom Meeting",
        "image": "https://alumni.creighton.edu/sites/default/files/externals/7fe45be3aa4b9a7e7698f971033cbcc6.jpg",
        "featured": true,
        "organizer": "Inua Advocacy",
        "status": "past",
        "contact": {
          "email": "info@inuaadvocacy.org",
          "phone": "+265 882 717 995",
          "whatsapp": "+265 882 717 995"
        },
        "registration": {
          "required": true,
          "url": "https://us06web.zoom.us/meeting/register/4PrLQ4aMSK6gzSDff2shWw",
          "deadline": "2025-04-24"
        },
        "tags": ["Refugees", "Malawi", "Laws", "Inua Advocacy"]
      }
    ]
  }
}
```

## POST /api/events

Retrieve events data with optional metadata and statistics.

### Request Body

<ParamField body="options" type="object">
  Optional configuration for the response

  <ParamField body="includeMetadata" type="boolean">
    Include export metadata in response
  </ParamField>

  <ParamField body="includeStats" type="boolean">
    Include statistics in response
  </ParamField>
</ParamField>

### Response Format

Same as GET endpoint, with optional additional fields:

<ResponseField name="metadata" type="object">
  Export metadata (only if `includeMetadata: true`)

  <ResponseField name="exportDate" type="string">
    ISO 8601 timestamp of export
  </ResponseField>

  <ResponseField name="collection" type="string">
    Collection name
  </ResponseField>
</ResponseField>

<ResponseField name="stats" type="object">
  Statistics (only if `includeStats: true`)

  <ResponseField name="totalItems" type="number">
    Total number of items
  </ResponseField>

  <ResponseField name="collection" type="string">
    Collection name
  </ResponseField>
</ResponseField>

### Example Request

```bash theme={null}
curl -X POST "https://services.dzaleka.com/api/events" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "includeMetadata": true,
      "includeStats": true
    }
  }'
```

### Example Response

```json theme={null}
{
  "status": "success",
  "count": 28,
  "data": {
    "events": [
      {
        "id": "Breaking Myths About Refugees",
        "title": "Breaking Myths About Refugees: Truths That Change Perceptions",
        "date": "2025-04-24T13:00:00.000Z",
        "location": "Online"
      }
    ]
  },
  "metadata": {
    "exportDate": "2025-03-09T12:00:00.000Z",
    "collection": "events"
  },
  "stats": {
    "totalItems": 28,
    "collection": "events"
  }
}
```

## Implementation

The Events API is implemented using the `createGetHandler` and `createPostHandler` utility functions from `src/utils/api-utils.ts:118`.

Source code: `src/pages/api/events.ts:5`