Awards and obligations

Choose the award representation that fits the task. These endpoints expose published award data, not a guarantee of complete action history for every award.

Access	Use it for	Identifier
`GET /api/v1/awards`	A small, convenient award view	`data[].id` is the exact USAspending award key
`GET /api/v1/awards/{award_id}`	One convenience award	Use the exact returned `id`
`GET /api/v1/datasets/awards`	Full published award fields and exact filters	`attributes.id` is an award UUID; `record_id` is the lookup ID
`GET /api/v1/datasets/summary-awards`	Baseline award summaries, ownership basis and promotion rules	`attributes.award_key` is the external award key

Search convenience awards

curl --fail-with-body --get 'https://app.defdex.io/api/v1/awards' \
  --header "Authorization: Bearer $DEFDEX_API_KEY" \
  --data-urlencode 'q=radar' \
  --data-urlencode 'limit=10'

Convenience search checks the title only. company_id is an exact organization UUID and filters ultimate_parent_id; it does not mean every direct-recipient award. The response contains id, title, obligated_usd, ceiling_usd, company_id and source URLs, plus build_id and next_cursor on lists.

Filter full award records

Use GET /datasets/awards and exact JSON filters for recipient_id, ultimate_parent_id, awarding_agency_id, funding_agency_id, awarding_office_id, program_id, recipient_uei, award_key and other published fields. q searches only the descriptive fields that exist on that collection, not every column.

Read action history

summary-award-actions requires a non-null exact award_key filter:

curl --fail-with-body --get \
  'https://app.defdex.io/api/v1/datasets/summary-award-actions' \
  --header "Authorization: Bearer $DEFDEX_API_KEY" \
  --data-urlencode 'filters={"award_key":"EXACT_RETURNED_AWARD_KEY"}' \
  --data-urlencode 'limit=100'

Use the key returned from actual data, not the placeholder above. Follow pagination. award-fiscal-years, summary-reviewed-award-years and company/agency summary collections provide other published grains; check the catalog before joining them.

Interpret dollars and ownership

Obligations may be positive, zero or negative. Keep reversals and deobligations in net totals. potential_value_usd and the convenience ceiling_usd describe potential value, not spending. IDVs are vehicles; avoid counting their ceiling alongside task order spending. Requested and enacted budget figures are separate measures.

Award lists can follow the latest owner while yearly totals follow the parent reported on each action. Preserve the published attribution basis, exact UEIs and period. Do not infer ownership from fuzzy names or assume every award is promoted into the same detail view. For unavailable detail, retain the exact external key and its USAspending source link.