> ## 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 # API Documentation Guide This guide explains how the GDELT Cloud developer API documentation is structured and maintained. ## Overview GDELT Cloud uses [Mintlify](https://mintlify.com) as its documentation platform. The docs expose a single **API Reference** tab: * **v2** is the primary surface, generated from `gdelt-cloud-docs/api-reference/openapi-v2.json`, with hand-written Overview pages (`v2.mdx`, `concepts.mdx`, `taxonomy.mdx`, `cookbook.mdx`). * **Legacy v1** is a collapsed group at the bottom of the same tab, generated from the legacy `openapi-*.json` specs. The v2 spec is hand-maintained to match the clean public product contract. The v1 specs are maintained for existing direct API users (deprecation pending). *** ## 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 | | GET | `/api/v2/energy/assets` | Search GEM Energy assets | | GET | `/api/v2/energy/assets/summary` | Energy asset rollups | | GET | `/api/v2/energy/assets/map` | Energy map aggregate/fine rows | | GET | `/api/v2/energy/assets/{tracker}/{gem_id}` | Fetch a known Energy asset | ### 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: ```bash theme={null} python3 scripts/build_openapi.py ``` This script lives at `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 single **API Reference** tab hand-groups v2 endpoints (Events, Stories, Entities, Geography, Energy, Briefs, then a collapsed **Preview · Coming soon** section, then a collapsed **Legacy v1 API** group). v2 endpoints are referenced **inline** so we control grouping and ordering; v1 groups auto-generate from their specs via `{ source, directory }`. ```json theme={null} { "tab": "API Reference", "openapi": "api-reference/openapi-v2.json", "groups": [ { "group": "Overview", "icon": "book-open", "pages": ["api-reference/v2", "api-reference/concepts", "api-reference/taxonomy", "api-reference/cookbook"] }, { "group": "Events", "icon": "bolt", "openapi": "api-reference/openapi-v2.json", "pages": [ { "openapi": "GET /api/v2/events" } ] } ] } ``` **Critical gotchas (learned the hard way):** 1. **Inline `{ "openapi": "GET /path" }` refs only resolve when the spec is declared at the tab or group level** (`"openapi": "api-reference/openapi-v2.json"`). A global `api.openapi` array is **not** sufficient — without the tab/group declaration, every inline ref silently generates nothing. We declare it at the tab level *and* on each group that holds inline refs. 2. **Generated page slugs come from the operation's OpenAPI `tags`, not the nav group name** (e.g. an op tagged `Entities` lands at `/api-reference/entities/...` even if placed in another group). So **tag and group names must avoid `&` and other URL-hostile characters** — an `&` in a tag/group name breaks slug generation and the pages silently disappear. Use "and" (e.g. `Screening and Reference`). 3. **Only top-level groups always expand;** nested groups honor `"expanded": false`. The Preview and Legacy sections are top-level parents whose children are nested groups, so they collapse by default. The Overview pages (`v2.mdx`, `concepts.mdx`, `taxonomy.mdx`, `cookbook.mdx`) and the v1 overview (`introduction.mdx`) are manually maintained. Endpoint pages are generated from the OpenAPI specs. **Before pushing, verify locally** with the Mintlify CLI from `gdelt-cloud-docs/`: ```bash theme={null} mint openapi-check api-reference/openapi-v2.json # spec valid node scripts/validate-v2-openapi.mjs # repo gate (3.0.3, ApiKeyAuth, examples) mint dev # render + check the sitemap lists every endpoint mint broken-links # no broken internal links ``` *** ## Authentication All `/api/v1/*` endpoints require: ``` Authorization: Bearer gdelt_sk_<64-hex-chars> ``` API keys are managed in the GDELT Cloud dashboard under **Settings → API Keys**. *** ## 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 |