Search and inspect awarded government contracts.
openapi: 3.1.0
info:
title: Govly Tools API (Alpha) Awards API
version: 1.0.0-alpha
description: 'ALPHA / UNSTABLE: This API is still in active development. Endpoint behavior, request fields, response fields, error codes, and operation names may change before the Tools API is declared stable.
REST-callable tool surface for agent and automation workflows. Agents are the primary consumer, but integrations can be built on this API. Responses are JSON for typed clients; MCP tools may render action results into text-oriented formats separately.
'
servers:
- url: https://app.govly.com
security:
- bearerApiKey: []
- headerApiKey: []
tags:
- name: Awards
description: Search and inspect awarded government contracts.
paths:
/api/tools/v1/awards/{id}:
get:
tags:
- Awards
operationId: show_award
summary: Show an award
description: 'Show a single awarded contract with transactions, sub-awards, related opportunities, program links, line items, places, classification codes, and contacts. The path parameter accepts either identifier shape: an all-digit value is treated as the Govly award database id; anything else is treated as the award uniqueKey (such as CONT_AWD_... or CONT_IDV_...).
'
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Award
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Award'
'401':
$ref: '#/components/responses/Error'
'403':
$ref: '#/components/responses/Error'
'404':
$ref: '#/components/responses/Error'
/api/tools/v1/awards/search:
post:
tags:
- Awards
operationId: search_awards
summary: Search awards
description: 'Search awarded government contracts with the constrained public parameter set shared by MCP search_awards. Searches all time unless dateRange is given. searchType defaults to the authenticated user''s market focus (fed or sled); sled and international require the matching organization subscription.
'
requestBody:
required: false
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
query:
type: string
description: Search text. Supports keywords, quoted phrases, and boolean operators such as AND, OR, and NOT.
cursor:
type: string
description: 'Opaque pagination token from the previous response''s meta.nextCursor. Omit for the first page. Tokens are bound to the query, filters, and sort inputs and carry no format guarantee.
'
perPage:
type: integer
default: 25
maximum: 100
searchType:
type: string
enum:
- fed
- sled
- international
description: 'Market type. Defaults to the authenticated user''s market focus (fed or sled). sled and international require the matching organization subscription.
'
dateRange:
type: array
items:
type: string
minItems: 2
maxItems: 2
description: Filter by award action dates as [start, end] in ISO 8601 format. Searches all time when omitted.
recipientNames:
type: array
items:
type: string
description: Filter to awards won by any of these recipient (vendor) names.
buyerNames:
type: array
items:
type: string
description: Filter to awards bought by any of these government buyer names.
funderNames:
type: array
items:
type: string
description: Filter to awards funded by any of these government funder names.
naics:
type: array
items:
type: string
description: NAICS codes to filter by, such as 334111.
psc:
type: array
items:
type: string
description: Product or service codes (PSC) to filter by.
amountRange:
type: array
items:
type: number
minItems: 2
maxItems: 2
description: Filter by award amount as [minimum, maximum].
sort:
type: string
enum:
- period_of_performance_start_date
- awarded_date
- last_modified_date
- award_amount
description: Sort field. Defaults to period_of_performance_start_date. Use awarded_date for recency or award_amount for contract size. SLED awards often lack period_of_performance_start_date, so prefer awarded_date when searchType is sled.
sortDirection:
type: string
enum:
- asc
- desc
responses:
'200':
description: Matching awards
content:
application/json:
schema:
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: '#/components/schemas/Award'
meta:
$ref: '#/components/schemas/CursorMeta'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'403':
$ref: '#/components/responses/Error'
'422':
$ref: '#/components/responses/Error'
components:
schemas:
AwardGovernmentEntity:
type: object
properties:
id:
type: string
name:
type: string
code:
type: string
Award:
type: object
required:
- id
description: 'Stable external award shape. Empty members are omitted rather than rendered blank, and money fields are JSON numbers. Detail responses (show_award) add bounded collections; search responses return the summary shape.
'
properties:
id:
type: string
uniqueKey:
type: string
description: Stable award business key, such as CONT_AWD_... or CONT_IDV_....
displayName:
type: string
title:
type: string
identifier:
type: string
description:
type: string
aiSummary:
type: string
externalUrl:
type: string
awardUrl:
type: string
acquisitionType:
type: string
acquisitionCategory:
type: string
searchType:
type: string
enum:
- fed
- sled
- international
treasuryAccountIds:
type: array
items:
type: string
dates:
type: object
properties:
awardedDate:
type: string
lastModifiedDate:
type: string
periodOfPerformanceStartDate:
type: string
periodOfPerformanceEndDate:
type: string
periodOfPerformancePotentialEndDate:
type: string
amounts:
type: object
properties:
awardAmount:
type: number
obligatedAmount:
type: number
paidAmount:
type: number
ceilingAmount:
type: number
recipient:
type: object
properties:
name:
type: string
uniqueKey:
type: string
uei:
type: string
cageCode:
type: string
parentUniqueKey:
type: string
parentName:
type: string
buyer:
$ref: '#/components/schemas/AwardGovernmentEntity'
buyingOffice:
$ref: '#/components/schemas/AwardGovernmentEntity'
funder:
$ref: '#/components/schemas/AwardGovernmentEntity'
fundingOffice:
$ref: '#/components/schemas/AwardGovernmentEntity'
classification:
type: object
properties:
psc:
type: string
naics:
type: string
setAside:
type: object
properties:
id:
type: string
code:
type: string
name:
type: string
contractVehicle:
type: object
properties:
id:
type: string
slug:
type: string
name:
type: string
parentAward:
type: object
properties:
uniqueKey:
type: string
identifier:
type: string
jurisdiction:
type: object
properties:
id:
type: string
name:
type: string
isoCode:
type: string
transactions:
type: array
description: Detail only. Up to 100, newest action first.
items:
type: object
subAwards:
type: array
description: Detail only. Up to 100 award summaries.
items:
type: object
subAwardsCount:
type: integer
description: Detail only.
relatedOpportunities:
type: array
description: Detail only. Up to 25, newest posting first.
items:
type: object
programLinks:
type: array
description: Detail only. Up to 100.
items:
type: object
awardLineItems:
type: array
description: Detail only. Up to 100.
items:
type: object
places:
type: array
description: Detail only. AI-extracted places, most specific category first.
items:
type: object
classificationCodes:
type: array
description: Detail only. Up to 100 resolved classification codes with codeset.
items:
type: object
contacts:
type: array
description: Detail only. Up to 100 associated contacts (id, name, email).
items:
type: object
CursorMeta:
type: object
required:
- count
properties:
count:
type: integer
description: Number of records in this page.
totalCount:
type: integer
description: 'Total matching records (award search only), capped at 10,000 by the search engine. Pagination via nextCursor is not limited by this cap.
'
perPage:
type: integer
nextCursor:
type:
- string
- 'null'
ErrorEnvelope:
type: object
required:
- errors
properties:
errors:
type: array
items:
type: object
required:
- status
- code
- title
- detail
properties:
status:
type: string
code:
type: string
title:
type: string
detail:
type: string
source:
type: object
properties:
pointer:
type: string
responses:
Error:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
parameters:
id:
name: id
in: path
required: true
schema:
type: string
securitySchemes:
bearerApiKey:
type: http
scheme: bearer
bearerFormat: API key
headerApiKey:
type: apiKey
in: header
name: X-API-KEY