{"openapi":"3.1.0","info":{"title":"VelocityBids public bid data API","version":"1.0.0","summary":"Read-only aggregate statistics about US public bids, with the date, provenance, limits and a citation on every answer.","description":"Aggregates read from a fixed, dated data release (latest: 2026-11-01-r2, snapshot November 1, 2026). No account or key. No bid search, no individual bids and no bid documents. Every answer states its release, its dates, what it does not show and an address to cite. The same four questions are available to AI agents as an MCP server at https://www.velocitybids.ai/api/mcp (Streamable HTTP). Method: https://www.velocitybids.ai/insights/how-we-count-public-bids","contact":{"name":"VelocityBids","email":"hello@velocitybids.ai","url":"https://www.velocitybids.ai/developers"}},"servers":[{"url":"https://www.velocitybids.ai"}],"externalDocs":{"description":"Developer documentation","url":"https://www.velocitybids.ai/developers"},"tags":[{"name":"Public bid data"}],"paths":{"/api/v1/portals":{"get":{"operationId":"list_portals_by_state","summary":"List public bid portals by state","description":"List the public bid portals VelocityBids has confirmed are live, for one US state or for all states. Returns each portal's name, kind, address and the date its page was checked, plus the multi-state platforms. The list is partial: a missing portal is a gap in the directory, not proof the state has none. Aggregate directory only; no bids.","tags":["Public bid data"],"parameters":[{"name":"state","in":"query","required":false,"description":"A US state or DC, as a two-letter code (CO) or a name (Colorado).","schema":{"description":"A US state or DC, as a two-letter code (CO) or a name (Colorado).","type":"string","maxLength":40}}],"responses":{"200":{"description":"The answer, read from data release 2026-11-01-r2. Cached at the edge for up to an hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalsAnswer"}}}},"400":{"description":"A parameter is missing, unknown or not a US state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 calls from one address in an hour.","headers":{"Retry-After":{"description":"Seconds until the hour ends.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/statistics":{"get":{"operationId":"get_statistics_by_state","summary":"Get public bid statistics for a state","description":"Get aggregate public bid statistics for one US state: cleared bids due in the period, sources and platforms, open bids and the share with documents, the typical time to respond, and how fast bids were first seen. A figure rests on at least 150 bids or is null. Counts describe the VelocityBids collection, not the whole market. No individual bids.","tags":["Public bid data"],"parameters":[{"name":"state","in":"query","required":true,"description":"A US state or DC, as a two-letter code (CO) or a name (Colorado).","schema":{"type":"string","minLength":2,"maxLength":40,"description":"A US state or DC, as a two-letter code (CO) or a name (Colorado)."}}],"responses":{"200":{"description":"The answer, read from data release 2026-11-01-r2. Cached at the edge for up to an hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatisticsAnswer"}}}},"400":{"description":"A parameter is missing, unknown or not a US state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 calls from one address in an hour.","headers":{"Retry-After":{"description":"Seconds until the hour ends.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/response-window":{"get":{"operationId":"get_response_window","summary":"Get how long buyers give to respond to a bid","description":"Get how many calendar days public buyers give between posting a bid and its due date: the national median and spread, and the same for one state where the release publishes it. Covers only bids with a posting date from the source. Aggregate only.","tags":["Public bid data"],"parameters":[{"name":"state","in":"query","required":false,"description":"A US state or DC, as a two-letter code (CO) or a name (Colorado).","schema":{"description":"A US state or DC, as a two-letter code (CO) or a name (Colorado).","type":"string","maxLength":40}}],"responses":{"200":{"description":"The answer, read from data release 2026-11-01-r2. Cached at the edge for up to an hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseWindowAnswer"}}}},"400":{"description":"A parameter is missing, unknown or not a US state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 calls from one address in an hour.","headers":{"Retry-After":{"description":"Seconds until the hour ends.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/release":{"get":{"operationId":"get_release_info","summary":"Get the data release behind the answers","description":"Get the date, rule version, row counts, precision and file list of the data release every other answer is read from, plus the headline figures with their dates and sample sizes. Call this to cite or check a release.","tags":["Public bid data"],"parameters":[],"responses":{"200":{"description":"The answer, read from data release 2026-11-01-r2. Cached at the edge for up to an hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseAnswer"}}}},"400":{"description":"A parameter is missing, unknown or not a US state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 300 calls from one address in an hour.","headers":{"Retry-After":{"description":"Seconds until the hour ends.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"PortalsAnswer":{"type":"object","properties":{"release":{"type":"string","description":"Id of the data release the figures come from, such as 2026-11-01."},"asOf":{"type":"string","description":"Date of the snapshot the release was built from (YYYY-MM-DD)."},"period":{"type":"string","description":"The dates the figures cover, and whether they are by due date or as of one day."},"provenance":{"type":"string","description":"Where the figures come from and how they were produced."},"limits":{"type":"array","items":{"type":"string"},"description":"What the figures do not show. Read these before relying on a number."},"citation":{"type":"object","properties":{"title":{"type":"string","description":"Name of the page or file that backs the figures."},"url":{"type":"string","format":"uri","description":"Public address of that page or file. Cite this."},"citeAs":{"type":"string","description":"A ready-to-use citation line."}},"required":["title","url","citeAs"],"additionalProperties":false},"methodUrl":{"type":"string","format":"uri","description":"The page that explains the method behind every release figure."},"dataFiles":{"type":"array","items":{"type":"string","format":"uri"},"description":"The release files the figures were read from."},"data":{"type":"object","properties":{"state":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"],"additionalProperties":false},{"type":"null"}],"description":"The state asked for, or null when no state was given."},"portals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"state":{"type":"string","description":"Two-letter code, or an empty string for a portal that is not tied to one state."},"kind":{"type":"string"},"url":{"type":"string","format":"uri"},"verifiedOn":{"type":"string"},"httpStatus":{"type":"number"}},"required":["name","state","kind","url","verifiedOn","httpStatus"],"additionalProperties":false},"description":"Portals tied to the state asked for, or to any state when none was given."},"multiBuyerPlatforms":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"state":{"type":"string","description":"Two-letter code, or an empty string for a portal that is not tied to one state."},"kind":{"type":"string"},"url":{"type":"string","format":"uri"},"verifiedOn":{"type":"string"},"httpStatus":{"type":"number"}},"required":["name","state","kind","url","verifiedOn","httpStatus"],"additionalProperties":false},"description":"Portals shared by buyers in many states. Listed whatever state is asked for."},"directory":{"type":"object","properties":{"portalsListed":{"type":"number"},"candidatesChecked":{"type":"number"},"leftOutByRule":{"type":"number"},"couldNotConfirm":{"type":"number"},"verifiedOn":{"type":"string"}},"required":["portalsListed","candidatesChecked","leftOutByRule","couldNotConfirm","verifiedOn"],"additionalProperties":false}},"required":["state","portals","multiBuyerPlatforms","directory"],"additionalProperties":false}},"required":["release","asOf","period","provenance","limits","citation","methodUrl","dataFiles","data"],"additionalProperties":false},"StatisticsAnswer":{"type":"object","properties":{"release":{"type":"string","description":"Id of the data release the figures come from, such as 2026-11-01."},"asOf":{"type":"string","description":"Date of the snapshot the release was built from (YYYY-MM-DD)."},"period":{"type":"string","description":"The dates the figures cover, and whether they are by due date or as of one day."},"provenance":{"type":"string","description":"Where the figures come from and how they were produced."},"limits":{"type":"array","items":{"type":"string"},"description":"What the figures do not show. Read these before relying on a number."},"citation":{"type":"object","properties":{"title":{"type":"string","description":"Name of the page or file that backs the figures."},"url":{"type":"string","format":"uri","description":"Public address of that page or file. Cite this."},"citeAs":{"type":"string","description":"A ready-to-use citation line."}},"required":["title","url","citeAs"],"additionalProperties":false},"methodUrl":{"type":"string","format":"uri","description":"The page that explains the method behind every release figure."},"dataFiles":{"type":"array","items":{"type":"string","format":"uri"},"description":"The release files the figures were read from."},"data":{"type":"object","properties":{"state":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"],"additionalProperties":false},"published":{"type":"boolean","description":"False when the release publishes no figures for this state."},"collection":{"anyOf":[{"type":"object","properties":{"clearedBidsDue":{"type":"number","description":"Cleared bids due in the period."},"sources":{"type":"number"},"platforms":{"type":"number"},"topPlatformSharePercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"datedBids":{"type":"number","description":"Of the cleared bids, how many carry a posting date from the source."}},"required":["clearedBidsDue","sources","platforms","topPlatformSharePercent","datedBids"],"additionalProperties":false},{"type":"null"}]},"responseWindow":{"anyOf":[{"type":"object","properties":{"bidsMeasured":{"type":"number"},"p10Days":{"type":"number"},"medianDays":{"type":"number"},"p90Days":{"type":"number"}},"required":["bidsMeasured","p10Days","medianDays","p90Days"],"additionalProperties":false},{"type":"null"}],"description":"Calendar days from posting to due date. Null where fewer than 150 bids carry a posting date."},"openBids":{"anyOf":[{"type":"object","properties":{"count":{"type":"number"},"withDocumentsPercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"asOf":{"type":"string"}},"required":["count","withDocumentsPercent","asOf"],"additionalProperties":false},{"type":"null"}],"description":"Open bids in the collection and the share with at least one document we downloaded."},"collectionSpeed":{"anyOf":[{"type":"object","properties":{"bidsMeasured":{"type":"number"},"medianDaysFromPostingToFirstSeen":{"type":"number"}},"required":["bidsMeasured","medianDaysFromPostingToFirstSeen"],"additionalProperties":false},{"type":"null"}],"description":"How fast we first saw a bid after the buyer posted it. A measure of our collection, not of the buyer."}},"required":["state","published","collection","responseWindow","openBids","collectionSpeed"],"additionalProperties":false}},"required":["release","asOf","period","provenance","limits","citation","methodUrl","dataFiles","data"],"additionalProperties":false},"ResponseWindowAnswer":{"type":"object","properties":{"release":{"type":"string","description":"Id of the data release the figures come from, such as 2026-11-01."},"asOf":{"type":"string","description":"Date of the snapshot the release was built from (YYYY-MM-DD)."},"period":{"type":"string","description":"The dates the figures cover, and whether they are by due date or as of one day."},"provenance":{"type":"string","description":"Where the figures come from and how they were produced."},"limits":{"type":"array","items":{"type":"string"},"description":"What the figures do not show. Read these before relying on a number."},"citation":{"type":"object","properties":{"title":{"type":"string","description":"Name of the page or file that backs the figures."},"url":{"type":"string","format":"uri","description":"Public address of that page or file. Cite this."},"citeAs":{"type":"string","description":"A ready-to-use citation line."}},"required":["title","url","citeAs"],"additionalProperties":false},"methodUrl":{"type":"string","format":"uri","description":"The page that explains the method behind every release figure."},"dataFiles":{"type":"array","items":{"type":"string","format":"uri"},"description":"The release files the figures were read from."},"data":{"type":"object","properties":{"state":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"],"additionalProperties":false},{"type":"null"}]},"measures":{"type":"string","description":"Exactly what a response window is in these figures."},"national":{"type":"object","properties":{"bidsMeasured":{"type":"number"},"p10Days":{"type":"number"},"p25Days":{"type":"number"},"medianDays":{"type":"number"},"p75Days":{"type":"number"},"p90Days":{"type":"number"},"percentUnder7Days":{"anyOf":[{"type":"number"},{"type":"null"}]},"percentUnder14Days":{"anyOf":[{"type":"number"},{"type":"null"}]},"percentUnder21Days":{"anyOf":[{"type":"number"},{"type":"null"}]},"percent21DaysOrMore":{"anyOf":[{"type":"number"},{"type":"null"}]},"percent30DaysOrMore":{"anyOf":[{"type":"number"},{"type":"null"}]},"percent45DaysOrMore":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["bidsMeasured","p10Days","p25Days","medianDays","p75Days","p90Days","percentUnder7Days","percentUnder14Days","percentUnder21Days","percent21DaysOrMore","percent30DaysOrMore","percent45DaysOrMore"],"additionalProperties":false,"description":"All cleared US state and local bids in the release."},"forState":{"anyOf":[{"type":"object","properties":{"bidsMeasured":{"type":"number"},"p10Days":{"type":"number"},"medianDays":{"type":"number"},"p90Days":{"type":"number"}},"required":["bidsMeasured","p10Days","medianDays","p90Days"],"additionalProperties":false},{"type":"null"}],"description":"The state asked for. Null when no state was given or the release publishes none for it."},"datedSharePercent":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Share of cleared bids that carry a posting date and so enter any response-window figure."}},"required":["state","measures","national","forState","datedSharePercent"],"additionalProperties":false}},"required":["release","asOf","period","provenance","limits","citation","methodUrl","dataFiles","data"],"additionalProperties":false},"ReleaseAnswer":{"type":"object","properties":{"release":{"type":"string","description":"Id of the data release the figures come from, such as 2026-11-01."},"asOf":{"type":"string","description":"Date of the snapshot the release was built from (YYYY-MM-DD)."},"period":{"type":"string","description":"The dates the figures cover, and whether they are by due date or as of one day."},"provenance":{"type":"string","description":"Where the figures come from and how they were produced."},"limits":{"type":"array","items":{"type":"string"},"description":"What the figures do not show. Read these before relying on a number."},"citation":{"type":"object","properties":{"title":{"type":"string","description":"Name of the page or file that backs the figures."},"url":{"type":"string","format":"uri","description":"Public address of that page or file. Cite this."},"citeAs":{"type":"string","description":"A ready-to-use citation line."}},"required":["title","url","citeAs"],"additionalProperties":false},"methodUrl":{"type":"string","format":"uri","description":"The page that explains the method behind every release figure."},"dataFiles":{"type":"array","items":{"type":"string","format":"uri"},"description":"The release files the figures were read from."},"data":{"type":"object","properties":{"release":{"type":"string"},"snapshotAt":{"type":"string"},"ruleVersion":{"type":"string"},"codeRevision":{"type":"string"},"window":{"type":"string","description":"The due-date window the state and response-window figures cover."},"rowCounts":{"type":"object","properties":{"rowsInSnapshot":{"type":"number"},"rowsInWindowBeforeRules":{"type":"number"},"clearedRowsInWindow":{"type":"number"}},"required":["rowsInSnapshot","rowsInWindowBeforeRules","clearedRowsInWindow"],"additionalProperties":false},"minimumBidsPerPublishedFigure":{"type":"number"},"statesWithFigures":{"type":"number"},"precision":{"type":"object","properties":{"sampleSize":{"type":"number"},"solicitationSharePercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"interval95Percent":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},"basis":{"type":"string"}},"required":["sampleSize","solicitationSharePercent","interval95Percent","basis"],"additionalProperties":false},"headlineFigures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"value":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string"}]},{"type":"null"}]},"unit":{"type":"string"},"period":{"type":"string"},"sampleSize":{"type":"number"},"kind":{"type":"string","enum":["observed","estimated"]},"measures":{"type":"string"}},"required":["id","label","value","unit","period","sampleSize","kind","measures"],"additionalProperties":false}},"files":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"sha256":{"type":"string"},"bytes":{"type":"number"}},"required":["name","url","sha256","bytes"],"additionalProperties":false}},"otherReleases":{"type":"array","items":{"type":"string"}}},"required":["release","snapshotAt","ruleVersion","codeRevision","window","rowCounts","minimumBidsPerPublishedFigure","statesWithFigures","precision","headlineFigures","files","otherReleases"],"additionalProperties":false}},"required":["release","asOf","period","provenance","limits","citation","methodUrl","dataFiles","data"],"additionalProperties":false}}}}