Skip to main content

​
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 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

​
v1 endpoints documented

​
Regenerating the OpenAPI Spec

When you add, remove, or change a /api/v1/* endpoint, regenerate the v1 specs by running:
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

​
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 }.
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/:

​
Authentication

All /api/v1/* endpoints require:
API keys are managed in the GDELT Cloud dashboard under Settings → API Keys.

​
Error Codes