Build on GlobalGov

Getting started

Who can access the API

The MCP server has a genuinely free tier — https://freemcp.globalgov.io/mcp, no key, no sign-in (see Connect an assistant). Full programmatic access (the AI brief, live feed, full-depth pagination, all regions, and the REST + Developer API) is a paid add-on:

• The API & MCP add-on is $400/mo, available only on the Global and Enterprise plans.
• It is not included in any plan — even Global and Enterprise purchase it separately as an add-on (it is not bundled or free).
• Essentials, Intelligence, and the Free Trial are not eligible — upgrade to Global or Enterprise to add it.

All 5 MCP tools work with no key at all at teaser depth (platform stats, search, factual record lookups, related opportunities) — see Free tier vs. paid tier.

Get an API key

1. Sign in and open Settings → API & MCP Access (/settings/api).
2. If your plan doesn't already include API access, click Buy API Access to add the add-on.
3. Click Generate API key. Your key (format gg_…) is shown once — copy it immediately. It is stored hashed and can never be shown again; lose it and you regenerate.

Keys can be regenerated (rotated) or revoked at any time from the same page. Revoking a key breaks any assistant or integration still using it.

Base URLs & authentication

AI assistants authenticate over OAuth ("Sign in with GlobalGov"). For direct REST / BYO callers, authenticate every request with your key in the X-API-Key header:

X-API-Key: gg_your_key_here

All access is over HTTPS. Never embed a key in client-side/browser code or a public repository — treat it like a password.

MCP connector guide

The Model Context Protocol (MCP) is the open standard AI assistants use to connect to external tools and data. GlobalGov runs a remote MCP server so an assistant can search and read procurement intelligence on your behalf — no glue code required.

Start free. https://freemcp.globalgov.io/mcp needs no sign-in and no key — add it to any MCP client and all 5 tools appear at teaser depth. For the AI brief on each record, the live opportunity feed, full-depth pagination, and all your subscribed regions, use https://mcp.globalgov.io and sign in with GlobalGov (or send an X-API-Key header). https://mcp.globalgov.io/public is the same free teaser on the paid host. All are POST-only; GET/DELETE return 405, and JSON-RPC batching is not supported.

Connect an assistant

Start with the free URL https://freemcp.globalgov.io/mcp — no account, no key, no sign-in. It works on every client below that supports remote MCP. To unlock full depth (AI briefs, live feed, full pagination, all regions), swap in https://mcp.globalgov.io and either "Sign in with GlobalGov" (OAuth, zero-config via Dynamic Client Registration) or send an X-API-Key header. Verified against each vendor's current docs (2026).

Free, no sign-in

Paid-plan assistants

Every path hits the same tools. The free URL is the zero-config default; X-API-Key and OAuth on https://mcp.globalgov.io unlock full depth for scripts and assistants respectively.

Prefer the command line? With MCP tooling you can smoke-test the server directly:

npx @modelcontextprotocol/inspector
#   URL: https://mcp.globalgov.io   (runs the OAuth "Sign in with GlobalGov" flow)
#   or the keyless public twin: https://mcp.globalgov.io/public
#   or add an X-API-Key header to https://mcp.globalgov.io for BYO-key access

Free tier vs. paid tier

Access is resolved from your X-API-Key:

Access is resolved live on every call from your identity (OAuth sign-in or X-API-Key): a plan with API access gets all 5 tools, a free/trial account gets the 2 teaser tools. Calling a paid tool without a qualifying plan returns a tool error error="unavailable_for_tier" (not a crash). Anonymous callers on the public twin get the teaser too. Entitlement is never frozen in the token — downgrading a plan drops it back to the teaser immediately.

Free search shares the public site's per-visitor budget (a handful of searches per 24h); a paid key lifts that and is governed by the per-key hourly limit instead. See Rate limits.

The five tools

* required. Category enum: DEFENSE_SECURITY, INFRASTRUCTURE, HEALTH_SERVICES, ENERGY, TECHNOLOGY, PROFESSIONAL_SERVICES, CONSTRUCTION, LOGISTICS, HUMANITARIAN, ENVIRONMENTAL, RESEARCH_DEVELOPMENT, EDUCATION, OTHER.

search_solicitations

Full-text search over the corpus. Free callers get a teaser (teaser=true, up to 5 results, page 1) with the true match total; keyed callers get 20/page with pagination. If total_degraded=true, the exact count timed out and total is a floor.

POST https://mcp.globalgov.io
Content-Type: application/json
X-API-Key: gg_your_key_here

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_solicitations",
    "arguments": { "query": "cybersecurity training", "country": "US", "page": 1 }
  }
}

The result carries JSON in both the text content block and structuredContent:

{
  "results": [
    {
      "id": "6a3b7032-4989-4691-8465-9829d3306151",
      "title": "Cybersecurity Awareness Training Services",
      "agency_name": "Department of Homeland Security",
      "country_code": "US",
      "value_usd": 1250000.0,
      "currency": "USD",
      "deadline": "2026-08-15T17:00:00+00:00",
      "category": "DEFENSE_SECURITY",
      "slug": "dhs-cybersecurity-awareness-training-...",
      "description": "...",
      "rank": 0.8213
    }
  ],
  "total": 3184,
  "page": 1,
  "has_more": true,
  "total_degraded": false
}

get_platform_stats

Canonical coverage numbers, pre-computed and cached. No arguments.

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "get_platform_stats", "arguments": {} } }

{
  "solicitations_total": 9924001,
  "solicitations_active": 1062447,
  "countries_with_data": 223,
  "countries_live_coverage": 199,
  "source_systems_active": 69,
  "languages_supported": 46,
  "vendors_indexed": 2908349,
  "agencies_total": 175118,
  "forecasts_tracked": 1849,
  "market_coverage_usd": 13000000000000.0,
  "stats_verified_at": "2026-07-12"
}

Live numbers as returned by the endpoint; they grow daily.

get_solicitation API key

Full record by slug (preferred) or UUID — original + English title, agency, country, value/currency, deadline, status, category, NAICS/CPV, source_url, full description, and (when available) an AI-generated brief. Returns error="not_found" for unknown ids.

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "get_solicitation",
              "arguments": { "slug_or_id": "dhs-cybersecurity-awareness-training-..." } } }

get_related_solicitations API key

Up to 5 open solicitations related to a record (matched by country + NAICS, nearest deadline first). Argument: slug.

get_live_opportunity_feed API key

A random sample of 12 records from the curated live feed of open opportunities. No arguments. Served from a background-refreshed cache; if cold, returns a retryable warming_up error rather than an empty list.

Honest degraded states

GlobalGov never fakes an empty result. When a cache is cold or the database is under load, a tool returns an isError result whose JSON payload has a machine error code and a retryable flag:

REST API reference

The REST API serves the same corpus over plain HTTPS for back-end integrations. Two surfaces are live today:

• Public read endpoints — no key required, rate-limited per visitor. These power the MCP search tools.
• Key-authenticated endpoints — an X-API-Key on a plan with API access lifts the anonymous limits and unlocks the list endpoints below.

Base URL: https://globalgov.io/api/v1. All responses are JSON.

Building a new integration? Prefer the Developer API (REST v1) at https://globalgov.io/api/public/v1 — it's the versioned, contract-stable surface with explicit schemas, opaque IDs, cursor pagination, and scoped ggk_ keys, and it's live now. The endpoints below remain available for existing callers.

Authentication

Send your key in the X-API-Key header. Public /public/* read endpoints work without one.

curl "https://globalgov.io/api/v1/solicitations?limit=25" \
  -H "X-API-Key: gg_your_key_here"

Rate limits

Error format

Errors use the standard FastAPI shape with an HTTP status and a detail field:

// 429 — anonymous search budget exhausted
{ "detail": { "error": "rate_limit_exceeded",
              "searches_remaining": 0,
              "reset_at": "2026-07-21T00:19:59+00:00" } }

// 401 invalid key · 403 no API access · 404 not found
{ "detail": "Invalid API key" }

The Developer API (REST v1) uses the richer RFC 9457 problem+json error format with stable machine codes and a request_id — it is live now.

Public endpoints Free tier

No authentication. Rate-limited per visitor.

curl "https://globalgov.io/api/v1/public/stats"

curl "https://globalgov.io/api/v1/public/search?q=cybersecurity&country=US&limit=5"

curl "https://globalgov.io/api/v1/public/solicitations/ted-pl-poland-medical-consumables-...-291518-2025"

curl "https://globalgov.io/api/v1/public/solicitations/{slug}/related"

Key-authenticated endpoints API key

Require an X-API-Key on a plan with API access. List endpoints accept limit (≤100, default 25) and offset, and return { data: [...], total, has_more }.

curl "https://globalgov.io/api/v1/solicitations?limit=25&offset=0" \
  -H "X-API-Key: gg_your_key_here"

These endpoints return the full record objects. For a field-explicit, versioned contract with opaque IDs and cursor pagination, use the Developer API (REST v1) — live now — or the public / MCP surfaces.

Developer API (REST v1)

A versioned, read-only REST API over the full corpus — live now. Explicit response schemas (never raw records), opaque non-sequential IDs, cursor pagination, and RFC 9457 errors.

Get a key

In Settings → API & MCP Access generate a key (shown once, format ggk_live_…) — or a rate-limited sandbox key (environment: "test"). Keys carry least-privilege scopes: solicitations:read, awards:read, vendors:read, agencies:read. Keys are stored hashed, verified by an indexed O(1) lookup, and independently revocable.

curl "https://globalgov.io/api/public/v1/solicitations?limit=25&country=US" \
  -H "Authorization: Bearer ggk_live_your_key"

Endpoints

Every resource has a cursor-paginated list and a by-id lookup. IDs are opaque and non-sequential.

List params: limit (1–100, default 25), cursor (opaque), plus per-resource filters (e.g. country, naics, posted_after, active). Response envelope: { "data": […], "next_cursor": "…", "has_more": true }. Corpus results are scoped to your subscribed regions; no personal contact data is ever returned.

Errors & rate limits

Errors are application/problem+json (RFC 9457) with a stable machine code and a request_id: unauthorized, invalid_key, insufficient_scope, insufficient_tier, not_found, validation_error, rate_limited. Every response carries RateLimit-Limit/Remaining/Reset; live keys default to 1,000 req/hr, sandbox keys 60 req/hr.

On the roadmap

Live today: the four read resources above, scoped keys, sandbox keys, cursor pagination, and the OpenAPI spec. Still coming: Python/TypeScript SDKs, write access to your own pipeline/watchlist, a dedicated api.globalgov.io host, and a published 6-month deprecation policy. Tell us what you need next.

Support

Questions, a key that isn't working, or a feature request? Contact us or manage your key anytime in Settings → API & MCP Access.