Skip to main content

​
Welcome to the EcoEvents API

The EcoEvents API provides a comprehensive set of endpoints to manage sustainable events, track carbon footprints, coordinate vendors, and analyze environmental impact. Built on REST principles, our API uses predictable resource-oriented URLs, accepts JSON-encoded request bodies, and returns JSON-encoded responses.

​
Base URL

All API requests should be made to: 
https://api.ecoevents.com/v1
The API is only available over HTTPS. Requests made over plain HTTP will be redirected to HTTPS.

​
API Versioning

The EcoEvents API uses URL-based versioning. The current version is v1, which is included in the base URL. We maintain backward compatibility within major versions and provide advance notice before deprecating any endpoints. When breaking changes are introduced, we’ll release a new API version (e.g., v2) and maintain support for previous versions for at least 12 months.

​
Rate Limits

To ensure fair usage and system stability, API requests are rate-limited based on your subscription tier:
TierRequests per minuteRequests per day
Free601,000
Starter30010,000
Professional1,20050,000
EnterpriseCustomCustom
Rate limit information is included in response headers: 
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1678901234
When you exceed the rate limit, the API returns a 429 Too Many Requests response. Implement exponential backoff in your application to handle rate limit errors gracefully.

​
Response Format

All responses are returned in JSON format with appropriate HTTP status codes.

​
Success Response

Successful requests return a 2xx status code with the requested data: 
{
  "id": "evt_1a2b3c4d5e",
  "name": "Green Tech Summit 2026",
  "date": "2026-06-15T09:00:00Z",
  "location": "San Francisco Convention Center",
  "attendees": 500,
  "carbonFootprint": {
    "total": 12.5,
    "unit": "tonnes CO2e",
    "offset": true
  },
  "sustainabilityScore": 94,
  "status": "confirmed",
  "createdAt": "2026-03-01T10:30:00Z",
  "updatedAt": "2026-03-05T14:22:00Z"
}

​
Error Response

Errors return appropriate HTTP status codes with detailed error information: 
{
  "error": {
    "code": "invalid_request",
    "message": "The 'date' field is required and must be a valid ISO 8601 datetime",
    "field": "date",
    "documentation": "https://docs.ecoevents.com/api/errors#invalid_request"
  }
}

​
HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:
CodeStatusDescription
200OKRequest succeeded
201CreatedResource created successfully
204No ContentRequest succeeded with no response body
400Bad RequestInvalid request parameters
401UnauthorizedMissing or invalid authentication
403ForbiddenAuthenticated but not authorized
404Not FoundResource doesn’t exist
409ConflictRequest conflicts with current state
422Unprocessable EntityValid request but semantic errors
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error
503Service UnavailableTemporary server unavailability

​
Error Codes

In addition to HTTP status codes, error responses include specific error codes:
Error CodeDescription
authentication_failedInvalid API key or expired token
insufficient_permissionsMissing required permissions for operation
invalid_requestMalformed request or missing required fields
resource_not_foundRequested resource doesn’t exist
validation_errorRequest validation failed
rate_limit_exceededToo many requests
duplicate_resourceResource already exists
carbon_calculation_failedError calculating environmental impact
vendor_unavailableSustainable vendor service unavailable
payment_requiredSubscription upgrade required
Each error response includes a documentation URL pointing to detailed information about the error and how to resolve it.

​
Pagination

List endpoints support pagination using page and perPage query parameters: 
curl -X GET "https://api.ecoevents.com/v1/events?page=2&perPage=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
Pagination Parameters:
  • page (default: 1): Page number to retrieve
  • perPage (default: 20, max: 100): Number of items per page

​
Filtering and Sorting

Many list endpoints support filtering and sorting: 
# Filter events by date range and sustainability score
GET /v1/events?startDate=2026-06-01&endDate=2026-12-31&minScore=85

# Sort events by carbon footprint (ascending)
GET /v1/events?sortBy=carbonFootprint&order=asc

​
Idempotency

For POST and PATCH requests, you can include an Idempotency-Key header to safely retry requests without duplicating operations: 
curl -X POST "https://api.ecoevents.com/v1/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-12345" \
  -d '{"name": "Sustainable Future Summit"}'

​
Webhooks

EcoEvents supports webhooks to notify your application of events in real-time. Configure webhook endpoints in your dashboard to receive notifications for:
  • Event creation, updates, and cancellations
  • Carbon footprint calculations completed
  • Sustainability score changes
  • Vendor confirmations
  • Payment processing

​
SDK and Libraries

Official SDKs are available for popular programming languages:
  • Node.js: npm install @ecoevents/sdk
  • Python: pip install ecoevents
  • Ruby: gem install ecoevents
  • PHP: composer require ecoevents/sdk

​
Support

Need help? Reach out to our developer support team:
Enterprise customers have access to dedicated support channels and SLA guarantees. Contact your account manager for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us