Documentation Index
Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt
Use this file to discover all available pages before exploring further.
API Documentation Guide
This guide explains how the GDELT Cloud developer API documentation is structured and maintained.
Overview
GDELT Cloud uses Mintlify as its documentation platform. The docs expose two API reference tabs:
- V2 API Reference: generated from
gdelt-cloud-docs/api-reference/openapi-v2.json
- V1 API Reference: legacy specs generated from
gdelt-cloud-docs/api-reference/openapi*.json
The v2 spec is hand-maintained to match the clean public product contract. The v1 specs are maintained for existing direct API users.
Developer API — What We Document
The public docs expose API Key-authenticated /api/v2/* endpoints plus supported legacy /api/v1/* endpoints.
Internal browser/session APIs (/api/public/*, /api/dashboard/*, etc.) are intentionally excluded.
v2 endpoints documented
| Method | Path | Description |
|---|
| GET | /api/v2/events | List generated structured Events |
| GET | /api/v2/events/{event_id} | Fetch a known Event |
| GET | /api/v2/events/summary | Event rollups and trends |
| GET | /api/v2/stories | List generated clustered Stories |
| GET | /api/v2/stories/{story_id} | Fetch a known Story |
| GET | /api/v2/stories/{story_id}/articles | Paginated Story articles |
| GET | /api/v2/stories/summary | Story rollups and trends |
| GET | /api/v2/entities | Discover Entities |
| GET | /api/v2/entities/{entity_id} | Fetch an Entity profile |
| GET | /api/v2/geo/admin1 | Country-scoped admin1 discovery |
v1 endpoints documented
| Method | Path | Description |
|---|
| GET | /api/v1/media-events | List top media event clusters |
| GET | /api/v1/media-events/cluster | Get articles in a specific cluster |
| GET | /api/v1/entity | Look up a named entity (GDELT GKG) |
| GET | /api/v1/entity-geg | Look up a GEG entity (enhanced graph) |
| GET | /api/v1/domain | Look up a news domain/source |
| GET | /api/v1/conflict-events | List legacy Conflict events |
Regenerating the OpenAPI Spec
When you add, remove, or change a /api/v1/* endpoint, regenerate the v1 specs by running:
python3 scripts/build_openapi.py
scripts/build_openapi.py and writes to the v1 OpenAPI files under
gdelt-cloud-docs/api-reference/.
When you add, remove, or change a /api/v2/* endpoint, update api-reference/openapi-v2.json
and the overview page api-reference/v2.mdx in the same change. The v2 docs must remain testable in Mintlify’s API playground.
What the script contains
- All 5 endpoint definitions with full query parameter schemas
ApiKeyAuth security scheme (Bearer gdelt_sk_* format)- Standard response schemas (200 success, 401/403/429/500 errors)
- Server definition pointing to
https://gdeltcloud.com
When to run it
- After adding a new
/api/v1/* endpoint
- After changing query parameters on an existing endpoint
- After changing response shapes
- After changing authentication or error behavior
Documentation File Structure
gdelt-cloud-docs/
├── docs.json # Mintlify config & navigation
├── index.mdx # Home page
├── quickstart.mdx # Getting-started guide
├── authentication.mdx # Session + API key auth
├── api-reference/
│ ├── v2.mdx # Recommended API v2 overview
│ ├── openapi-v2.json # API v2 endpoint reference
│ ├── introduction.mdx # Legacy API v1 overview
│ └── openapi*.json # Legacy API v1 endpoint specs
├── developers/
│ └── api-keys.mdx # API key management, plans, code examples
├── features/
│ ├── research-agent.mdx
│ └── alerts.mdx
└── mcp/ # MCP Server documentation
Navigation
Navigation is configured in docs.json. The V2 API Reference and V1 API Reference tabs use Mintlify’s OpenAPI source feature to auto-generate one page per endpoint.
{
"tab": "V2 API Reference",
"groups": [
{
"group": "Overview",
"pages": ["api-reference/v2"]
},
{
"group": "V2 Endpoints",
"openapi": {
"source": "api-reference/openapi-v2.json",
"directory": "api-reference/v2-endpoints"
}
}
]
}
api-reference/v2.mdx) and v1 overview (api-reference/introduction.mdx) are manually maintained. Endpoint pages are generated from their OpenAPI specs.
Authentication
All /api/v1/* endpoints require:
Authorization: Bearer gdelt_sk_<64-hex-chars>
Error Codes
| HTTP | error field | Meaning |
|---|
| 401 | MISSING_API_KEY | No Authorization header |
| 401 | INVALID_API_KEY | Key not found / malformed |
| 403 | API_ACCESS_DENIED | Plan does not include API access |
| 429 | RATE_LIMITED | RPM limit exceeded |
| 429 | QUOTA_EXCEEDED | Monthly QU limit reached |
| 500 | INTERNAL_ERROR | Server error |
