{"openapi":"3.1.0","info":{"title":"GoveBid API","version":"1.0.0","summary":"Real-time global government tender intelligence — aggregated from SAM.gov, TED Europa, World Bank, AfDB, USA Spending and more.","description":"GoveBid streams **government procurement opportunities worldwide** through a single fast REST API.\n\n**Why this API**\n- 4+ official data sources (SAM.gov, TED Europa, World Bank, AfDB, USA Spending) — unified, deduplicated, normalized.\n- Sector & value-tier classification out of the box.\n- Full-text search across titles, descriptions and buyer names.\n- Self-service API keys: get one in **one HTTP call**, no signup form.\n- Built for **AI agents** — see `/mcp` for native Model Context Protocol access.\n\n**Get started in 30 seconds**\n```bash\n# 1. Get a free key instantly\ncurl -X POST https://govebid.com/api/v1/keys/instant\n\n# 2. Use it\ncurl -H 'X-API-Key: gb_…' https://govebid.com/api/v1/tenders?limit=5\n```\n\n**Authentication** — pass your key in either header: `X-API-Key` or `X-RapidAPI-Key`.\n\n**Plans** — Free (50/day) · Starter (500/day) · Pro (5,000/day) · Enterprise (10M/day). Upgrade via [govebid.com](https://govebid.com).","contact":{"name":"GoveBid","url":"https://govebid.com"},"license":{"name":"Commercial","url":"https://govebid.com/terms"}},"servers":[{"url":"https://govebid.com/api/v1","description":"Production"},{"url":"https://smart-agent-genesis.replit.app/api/v1","description":"Production (Replit)"}],"tags":[{"name":"Public","description":"Open endpoints — no key required."},{"name":"Tenders","description":"Search, list, and read government tenders."},{"name":"Keys","description":"Self-service API key issuance and usage."},{"name":"System","description":"Health & service metadata."}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key issued via `POST /keys/instant` or after a paid Paddle subscription. RapidAPI consumers may use `X-RapidAPI-Key` instead."}},"schemas":{"Tender":{"type":"object","required":["id","source","title"],"properties":{"id":{"type":"string","format":"uuid","example":"9e6175ca-dbbd-4ad6-981b-a4058fe1b56e"},"source":{"type":"string","enum":["SAM_GOV","TED_EUROPA","UNGM","WORLD_BANK","AFDB","USA_SPENDING"],"example":"TED_EUROPA"},"source_id":{"type":"string"},"external_id":{"type":["string","null"]},"title":{"type":"string","example":"Construction works — Coventry Post Office"},"description":{"type":["string","null"]},"organization":{"type":["string","null"],"description":"Buyer / awarding organization"},"country":{"type":["string","null"],"example":"GB"},"sector":{"type":["string","null"]},"category":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["active","closed","awarded","cancelled",null]},"value_amount":{"type":["number","null"],"example":1250000},"estimated_value_usd":{"type":["number","null"]},"value_tier":{"type":["string","null"],"enum":["micro","small","medium","large",null]},"value_currency":{"type":["string","null"],"example":"EUR"},"urgency_score":{"type":["integer","null"],"description":"0-100, higher = closer deadline / higher priority"},"quality_score":{"type":["number","null"]},"published_at":{"type":["string","null"],"format":"date-time"},"posted_date":{"type":["string","null"],"format":"date"},"deadline_at":{"type":["string","null"],"format":"date-time"},"deadline":{"type":["string","null"],"format":"date"},"source_url":{"type":["string","null"],"format":"uri"},"url":{"type":["string","null"],"format":"uri"},"cpv_codes":{"type":["array","null"],"items":{"type":"string"}},"naics_codes":{"type":["array","null"],"items":{"type":"string"}},"keywords":{"type":["array","null"],"items":{"type":"string"}},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"TenderListResponse":{"type":"object","properties":{"total":{"type":"integer","example":2849},"returned":{"type":"integer","example":20},"offset":{"type":"integer","example":0},"limit":{"type":"integer","example":20},"query_time_ms":{"type":"integer","example":14},"cached":{"type":"boolean","example":false},"tenders":{"type":"array","items":{"$ref":"#/components/schemas/Tender"}}}},"PublicStats":{"type":"object","properties":{"total_tenders":{"type":"integer","example":2849},"sources":{"type":"integer","example":4},"last_updated":{"type":"string","format":"date-time"},"by_source":{"type":"object","additionalProperties":{"type":"integer"},"example":{"USA_SPENDING":1323,"AFDB":997,"WORLD_BANK":500,"TED_EUROPA":29}}}},"TenderStats":{"type":"object","properties":{"total_tenders":{"type":"integer"},"by_source":{"type":"object","additionalProperties":{"type":"integer"}},"by_sector":{"type":"object","additionalProperties":{"type":"integer"}},"by_value_tier":{"type":"object","additionalProperties":{"type":"integer"}},"tenders_expiring_soon":{"type":"integer","description":"Active tenders with deadline within 7 days."},"last_updated":{"type":"string","format":"date-time"}}},"InstantKeyResponse":{"type":"object","properties":{"key":{"type":"string","example":"gb_b9037698d52ebf6ffb83a32a27d06f87f3680ec007889ccc"},"plan":{"type":"string","example":"free"},"daily_limit":{"type":"integer","example":50},"message":{"type":"string"}}},"Usage":{"type":"object","properties":{"plan":{"type":"string","example":"free"},"requests_today":{"type":"integer","example":12},"daily_limit":{"type":"integer","example":50},"requests_total":{"type":"integer","example":137},"remaining_today":{"type":"integer","example":38},"reset_in":{"type":"string","example":"9h22m"}}},"Health":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"db":{"type":"string","example":"connected"}}},"Error":{"type":"object","properties":{"detail":{"type":"string"}}}}},"security":[{"ApiKeyHeader":[]}],"paths":{"/public/stats":{"get":{"tags":["Public"],"summary":"Public catalog stats (no auth)","description":"Snapshot of total tenders, source count, breakdown by source, and last update timestamp. Safe to embed on landing pages.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicStats"}}}}}}},"/health":{"get":{"tags":["System"],"summary":"Liveness + database connectivity","security":[],"responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"Database unavailable"}}}},"/tenders":{"get":{"tags":["Tenders"],"summary":"List & filter tenders","parameters":[{"name":"source","in":"query","schema":{"type":"string","enum":["SAM_GOV","TED_EUROPA","UNGM","WORLD_BANK","AFDB","USA_SPENDING"]},"example":"TED_EUROPA"},{"name":"country","in":"query","description":"ISO 3166-1 alpha-2 (auto-uppercased)","schema":{"type":"string","minLength":2,"maxLength":2},"example":"FR"},{"name":"sector","in":"query","description":"Matches against `sector` OR `category` (ILIKE)","schema":{"type":"string"},"example":"construction"},{"name":"value_tier","in":"query","schema":{"type":"string","enum":["micro","small","medium","large"]}},{"name":"urgency","in":"query","description":"Minimum urgency_score (0–100)","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"deadline_before","in":"query","description":"ISO date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"deadline_after","in":"query","description":"ISO date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Paginated list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenderListResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Daily rate limit exceeded"}}}},"/tenders/{id}":{"get":{"tags":["Tenders"],"summary":"Get one tender by ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tender"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not found"}}}},"/tenders/search":{"post":{"tags":["Tenders"],"summary":"Full-text search across tenders","description":"PostgreSQL `to_tsvector` / `plainto_tsquery` search across title, organization, sector and country. Results are sorted by relevance and include a `relevance_score` field. For structured filters (source, country, value_tier, urgency, deadline windows), use `GET /tenders` instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Free-text query (English stemming)","example":"construction"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20}}}}}},"responses":{"200":{"description":"Matching tenders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenderListResponse"}}}},"401":{"description":"Unauthorized"},"429":{"description":"Rate limit exceeded"}}}},"/tenders/stats":{"get":{"tags":["Tenders"],"summary":"Aggregate stats across the catalog","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenderStats"}}}},"401":{"description":"Unauthorized"}}}},"/keys/instant":{"post":{"tags":["Keys"],"summary":"Issue a free API key instantly (no signup)","description":"Returns a brand-new free-tier key. **Show this once to the user — it is not retrievable later.**","security":[],"responses":{"200":{"description":"Key issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstantKeyResponse"}}}}}}},"/keys/usage":{"get":{"tags":["Keys"],"summary":"Current usage and quota for the calling key","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"description":"Unauthorized"}}}}},"x-rapidapi":{"category":"Business","pricing":["Freemium"],"longDescription":"Real-time global government tender feed for procurement teams, market intelligence platforms and AI agents."},"x-mcp":{"endpoint":"https://govebid.com/api/v1/mcp","transport":"streamable-http","description":"Native Model Context Protocol endpoint — discoverable by Claude, Cursor and any MCP-compatible AI agent."}}