{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "TenderScope API", "version": "1.2.0", "description": "Public tenders from EU TED, Armenia (ARMEPS) and the EAEU (zakupki.gov.ru) in one schema. The same four operations are available as MCP tools at /mcp." }, "servers": [ { "url": "https://tenderscope.app" } ], "paths": { "/v1/tenders/search": { "post": { "operationId": "searchTenders", "summary": "Search open tenders", "description": "MCP tool: search_tenders", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchInput" } } } }, "responses": { "200": { "description": "Up to 20 tender cards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchOutput" } } } }, "400": { "description": "invalid_input — the request does not match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked API key (sk_live_…)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "plan_required or limit_reached — the feature or limit needs a higher plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded — monthly call limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tenders/{id}": { "get": { "operationId": "getTender", "summary": "Get the full card of one tender", "description": "MCP tool: get_tender", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tender id from search results", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full tender card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenderFull" } } } }, "400": { "description": "invalid_input — the request does not match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked API key (sk_live_…)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "plan_required or limit_reached — the feature or limit needs a higher plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded — monthly call limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/watchlists": { "post": { "operationId": "addWatchlist", "summary": "Save filters as a watchlist", "description": "MCP tool: add_to_watchlist", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddWatchlistInput" } } } }, "responses": { "201": { "description": "Watchlist created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddWatchlistOutput" } } } }, "400": { "description": "invalid_input — the request does not match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked API key (sk_live_…)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "plan_required or limit_reached — the feature or limit needs a higher plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded — monthly call limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/alerts": { "get": { "operationId": "getDeadlineAlerts", "summary": "Open alerts from your watchlists, nearest deadline first", "description": "MCP tool: get_deadline_alerts", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Up to 50 alerts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertsOutput" } } } }, "400": { "description": "invalid_input — the request does not match the schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "unauthorized — missing, invalid or revoked API key (sk_live_…)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "plan_required or limit_reached — the feature or limit needs a higher plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "quota_exceeded — monthly call limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/health": { "get": { "operationId": "health", "summary": "Service and data sources status (for uptime monitors)", "security": [], "responses": { "200": { "description": "ok or degraded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "REST API key: sk_live_… (create it in the dashboard)" } }, "schemas": { "SearchInput": { "type": "object", "properties": { "q": { "type": "string", "maxLength": 500, "description": "Free-text query in English, Russian or Armenian, e.g. \"IT services, deadline > week\"" }, "countries": { "description": "Buyer countries, ISO 3166-1 alpha-2 (e.g. [\"DE\", \"AM\"])", "maxItems": 50, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, "cpv": { "description": "CPV codes or prefixes (e.g. [\"72\", \"48\"])", "maxItems": 50, "type": "array", "items": { "type": "string", "pattern": "^\\d{2,8}(-\\d)?$" } }, "minBudget": { "description": "Minimum estimated budget, in the tender currency", "type": "number", "minimum": 0 }, "maxBudget": { "description": "Maximum estimated budget, in the tender currency", "type": "number", "minimum": 0 }, "deadlineAfter": { "description": "Only tenders whose deadline is after this ISO 8601 date/datetime", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] }, "budgetCurrency": { "description": "Currency of minBudget/maxBudget (ISO 4217). When set, each tender budget is converted at fixed reference rates (updated quarterly), so EU (EUR, PLN, SEK…), Armenian (AMD) and Russian (RUB) tenders compare fairly; tenders in other currencies are skipped. When omitted, budgets are compared in each tender's own currency.", "type": "string", "enum": [ "EUR", "USD", "GBP", "CHF", "NOK", "ISK", "SEK", "DKK", "PLN", "CZK", "HUF", "RON", "BGN", "AMD", "RUB" ] }, "limit": { "default": 10, "description": "Number of results, 1–20 (default 10)", "type": "integer", "minimum": 1, "maximum": 20 } }, "required": [ "q" ] }, "SearchOutput": { "type": "object", "properties": { "results": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "subject": { "description": "What is procured: lot names from the tender (for Armenian tenders, from the invitation document), in the original language (e.g. Armenian), separated by \"; \". Omitted when unknown or the same as the title.", "type": "string" }, "buyer": { "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2", "type": [ "string", "null" ] }, "budget": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "null" } ], "description": "Estimated budget as a decimal string, e.g. \"125000.00\"" }, "currency": { "description": "ISO 4217", "type": [ "string", "null" ] }, "deadline": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "Submission deadline, ISO 8601 UTC" }, "url": { "type": "string" }, "source": { "type": "string", "enum": [ "ted", "gnumner", "eaeu" ] } }, "required": [ "id", "title", "buyer", "country", "budget", "currency", "deadline", "url", "source" ], "additionalProperties": false } }, "hint": { "description": "How to broaden the query when there are few or no results", "type": "string" }, "degradedSources": { "description": "Sources currently failing; data may be stale", "type": "array", "items": { "type": "string", "enum": [ "ted", "gnumner", "eaeu" ] } } }, "required": [ "results" ], "additionalProperties": false }, "TenderFull": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "subject": { "description": "What is procured: lot names from the tender (for Armenian tenders, from the invitation document), in the original language (e.g. Armenian), separated by \"; \". Omitted when unknown or the same as the title.", "type": "string" }, "buyer": { "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2", "type": [ "string", "null" ] }, "budget": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "null" } ], "description": "Estimated budget as a decimal string, e.g. \"125000.00\"" }, "currency": { "description": "ISO 4217", "type": [ "string", "null" ] }, "deadline": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "Submission deadline, ISO 8601 UTC" }, "url": { "type": "string" }, "source": { "type": "string", "enum": [ "ted", "gnumner", "eaeu" ] }, "status": { "type": "string", "enum": [ "open", "amended", "cancelled", "closed" ] }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "region": { "type": [ "string", "null" ] }, "lotsCount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "cpvCodes": { "description": "Omitted on the Free plan", "type": "array", "items": { "type": "string" } }, "okpd2Codes": { "description": "OKPD2 codes (EAEU sources); omitted on the Free plan", "type": "array", "items": { "type": "string" } }, "lots": { "description": "Omitted on the Free plan", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "budget": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "null" } ] }, "currency": { "type": [ "string", "null" ] }, "cpvCodes": { "type": "array", "items": { "type": "string" } } }, "required": [ "title", "budget", "currency", "cpvCodes" ], "additionalProperties": false } }, "docsUrl": { "description": "Links to tender documents; omitted on the Free plan", "type": "array", "items": { "type": "string" } }, "hint": { "type": "string" } }, "required": [ "id", "title", "buyer", "country", "budget", "currency", "deadline", "url", "source", "status", "publishedAt", "region", "lotsCount", "updatedAt" ], "additionalProperties": false }, "AddWatchlistInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Watchlist name" }, "filters": { "type": "object", "properties": { "q": { "description": "Free-text query (any language), e.g. \"IT services, Armenia\"", "type": "string", "maxLength": 500 }, "countries": { "description": "Buyer countries, ISO 3166-1 alpha-2 (e.g. [\"DE\", \"AM\"])", "maxItems": 50, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, "cpv": { "description": "CPV codes or prefixes (e.g. [\"72\", \"48\"])", "maxItems": 50, "type": "array", "items": { "type": "string", "pattern": "^\\d{2,8}(-\\d)?$" } }, "minBudget": { "description": "Minimum estimated budget, in the tender currency", "type": "number", "minimum": 0 }, "maxBudget": { "description": "Maximum estimated budget, in the tender currency", "type": "number", "minimum": 0 }, "deadlineAfter": { "description": "Only tenders whose deadline is after this ISO 8601 date/datetime", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] }, "budgetCurrency": { "description": "Currency of minBudget/maxBudget (ISO 4217). When set, each tender budget is converted at fixed reference rates (updated quarterly), so EU (EUR, PLN, SEK…), Armenian (AMD) and Russian (RUB) tenders compare fairly; tenders in other currencies are skipped. When omitted, budgets are compared in each tender's own currency.", "type": "string", "enum": [ "EUR", "USD", "GBP", "CHF", "NOK", "ISK", "SEK", "DKK", "PLN", "CZK", "HUF", "RON", "BGN", "AMD", "RUB" ] } } }, "channels": { "default": { "email": true }, "type": "object", "properties": { "email": { "default": true, "description": "Send alerts by email", "type": "boolean" }, "webhook": { "description": "HTTPS endpoint for signed JSON alerts", "type": "string", "maxLength": 2048, "format": "uri" } } } }, "required": [ "name", "filters" ] }, "AddWatchlistOutput": { "type": "object", "properties": { "watchlistId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "estimatedMatches": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Open tenders matching the filters right now" }, "hint": { "description": "Note about the filters, e.g. which currency the budget range uses", "type": "string" } }, "required": [ "watchlistId", "estimatedMatches" ], "additionalProperties": false }, "AlertsOutput": { "type": "object", "properties": { "alerts": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "watchlistId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "watchlistName": { "type": "string" }, "reason": { "type": "string", "enum": [ "new", "deadline-24h", "amended" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "tender": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "subject": { "description": "What is procured: lot names from the tender (for Armenian tenders, from the invitation document), in the original language (e.g. Armenian), separated by \"; \". Omitted when unknown or the same as the title.", "type": "string" }, "buyer": { "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2", "type": [ "string", "null" ] }, "budget": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$" }, { "type": "null" } ], "description": "Estimated budget as a decimal string, e.g. \"125000.00\"" }, "currency": { "description": "ISO 4217", "type": [ "string", "null" ] }, "deadline": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "Submission deadline, ISO 8601 UTC" }, "url": { "type": "string" }, "source": { "type": "string", "enum": [ "ted", "gnumner", "eaeu" ] } }, "required": [ "id", "title", "buyer", "country", "budget", "currency", "deadline", "url", "source" ], "additionalProperties": false } }, "required": [ "watchlistId", "watchlistName", "reason", "createdAt", "tender" ], "additionalProperties": false } }, "hint": { "type": "string" } }, "required": [ "alerts" ], "additionalProperties": false }, "Error": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "invalid_input", "unauthorized", "plan_required", "limit_reached", "not_found", "quota_exceeded", "internal" ] }, "message": { "type": "string" } } } } }, "Health": { "type": "object", "required": [ "status", "sources" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "sources": { "type": "array", "items": { "type": "object", "required": [ "code", "status", "lastSuccessAt" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "ted", "gnumner", "eaeu" ] }, "status": { "type": "string", "enum": [ "ok", "error", "never", "stalled" ] }, "lastSuccessAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } } } } } } }