Developer Documentation

Build with the EarthOS API

Fast & Reliable

Edge-optimized endpoints with global CDN caching

Secure

API key authentication with rate limiting protection

Public Data

Access to public creators, events, and Earth Pulse data

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

x-earth-api-key: your_api_key_here

Request API access through our early access program. Once approved, you'll receive your API key via email.

Public Endpoints

GET/api/public/earthpulse

Get the current Earth Pulse state including cycle, phase, and color data.

{
  "pulse": {
    "cycle": 5,
    "phase": 12,
    "phaseName": "Waxing Gibbous",
    "colorShift": 150,
    "timestamp": "2025-12-12T10:30:00Z"
  }
}

GET/api/public/creators

Retrieve a list of public creators on EarthOS. Supports search, journey filtering, and pagination.

Query Parameters

q - Search by name, handle, or bio
journey - Filter by journey ID
limit - Number of results (max 100, default 40)
offset - Pagination offset (default 0)

[
  {
    "handle": "earthman",
    "displayName": "Earth Man",
    "avatarUrl": "https://...",
    "journeyId": "creation",
    "journeyName": "Creation",
    "bioPreview": "Building the operating system..."
  }
]

GET/api/public/creator/:handle

Get detailed information about a specific creator by their handle.

{
  "handle": "earthman",
  "displayName": "Earth Man",
  "avatarUrl": "https://...",
  "bio": "Full bio text...",
  "journeyId": "creation",
  "journeyName": "Creation",
  "links": [...],
  "stats": {...}
}

GET/api/public/events

Get upcoming public events on EarthOS with location and timing information.

Rate Limits

Free tier: 100 requests per hour
Creator tier: 1,000 requests per hour
Enterprise: Custom limits available

Example: Fetch Earth Pulse

JavaScript / TypeScript

const apiKey = process.env.EARTH_API_KEY;

const response = await fetch('https://earthos.world/api/public/earthpulse', {
  headers: {
    'x-earth-api-key': apiKey,
  },
});

const data = await response.json();
console.log('Current Earth Pulse:', data.pulse);

Support

Need help with the API? Have questions or feature requests?

Email us at api@earthos.world