> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.defdex.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.defdex.io/_mcp/server.

# 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

```sh
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:

```sh
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.