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 API Reference tab is auto-generated by Mintlify from the OpenAPI 3.0 spec located at: 
gdelt-cloud-docs/api-reference/openapi.json
The spec is hand-crafted and maintained via a Python build script — not auto-generated from Next.js routes. This is because the /api/v1/* routes use custom middleware rather than Zod schemas or @openapi JSDoc annotations.

​
Developer API — What We Document

Only the Developer API (API Key–authenticated /api/v1/* endpoints) is exposed in the public docs. Internal browser/session APIs (/api/public/*, /api/dashboard/*, etc.) are intentionally excluded.

​
Endpoints documented

MethodPathDescription
GET/api/v1/media-eventsList top media event clusters
GET/api/v1/media-events/clusterGet articles in a specific cluster
GET/api/v1/entityLook up a named entity (GDELT GKG)
GET/api/v1/entity-gegLook up a GEG entity (enhanced graph)
GET/api/v1/domainLook up a news domain/source
GET/api/v1/conflict-eventsList AI-coded ACLED-style conflict events

​
Regenerating the OpenAPI Spec

When you add, remove, or change a /api/v1/* endpoint, regenerate the spec by running: 
python3 scripts/build_openapi.py
This script lives at scripts/build_openapi.py and writes directly to gdelt-cloud-docs/api-reference/openapi.json.

​
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/
│   ├── introduction.mdx             # API overview, limits, error codes, reference codes
│   └── openapi.json                 # ← Generated by scripts/build_openapi.py
├── developers/
│   └── api-keys.mdx                 # API key management, plans, code examples
├── features/
│   ├── research-agent.mdx
│   └── alerts.mdx
└── mcp/                             # MCP Server documentation
Navigation is configured in docs.json. The API Reference tab uses Mintlify’s OpenAPI source feature — it reads openapi.json and auto-generates one page per endpoint. No manual MDX pages are needed for individual endpoints. 
{
  "tab": "API Reference",
  "groups": [
    {
      "group": "API Endpoints",
      "openapi": {
        "source": "api-reference/openapi.json",
        "directory": "api-reference"
      }
    }
  ]
}
The introduction page (api-reference/introduction.mdx) is not auto-generated — it is a manually maintained page that appears as the first page in the API Reference tab. To add it to the navigation, add it to the group pages list in docs.json if needed.

​
Plan Limits Reference

PlanQuery Units (QU/mo)Rate Limit
FreeNo API access—
ScoutNo API access—
Analyst10,000 QU30 RPM
ProfessionalUnlimited120 RPM
Each API call consumes 1 Query Unit. Rate limits are enforced per API key with a 60-second rolling window. The Retry-After header is returned on 429 responses.

​
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

HTTPerror fieldMeaning
401MISSING_API_KEYNo Authorization header
401INVALID_API_KEYKey not found / malformed
403API_ACCESS_DENIEDPlan does not include API access
429RATE_LIMITEDRPM limit exceeded
429QUOTA_EXCEEDEDMonthly QU limit reached
500INTERNAL_ERRORServer error