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

# Agencies, departments and offices

Read government organizations through the **organizations** collection with the
exact filter `type = "agency"`. There is no separate `/api/v1/agencies` route.
The same operation is available through both SDKs, CLI and MCP.

## List agencies

```sh
curl --fail-with-body --get \
  'https://app.defdex.io/api/v1/datasets/organizations' \
  --header "Authorization: Bearer $DEFDEX_API_KEY" \
  --data-urlencode 'filters={"type":"agency"}' \
  --data-urlencode 'limit=25'
```

```python
from defdex import DefDexClient
api = DefDexClient()
page = api.list("organizations", filters={"type": "agency"}, limit=25)
```

```sh
defdex list organizations --filters '{"type":"agency"}' --limit 25
```

For MCP, call `search_records` with
`{"dataset":"organizations","filters":{"type":"agency"},"limit":25}`.

## Choose the right level

| Field                  | Meaning                                                                         |
| ---------------------- | ------------------------------------------------------------------------------- |
| `id`                   | Organization UUID for joins and exact `id` filters                              |
| `sub_type`             | Broad grouping such as `department`, `sub_agency` or `office`                   |
| `agency_level`         | Published government hierarchy label, when present                              |
| `agency_code`          | Published agency code; preserve leading zeros                                   |
| `office_code`          | Published office code, when present                                             |
| `parent_id`            | Published direct parent                                                         |
| `navigation_parent_id` | Site navigation hierarchy; not a substitute for ownership or fiscal attribution |

Narrow a request with multiple exact filters, for example
`{"type":"agency","sub_type":"department"}`. Null hierarchy fields mean no
published value, not evidence that the organization has no parent.

## Read programs and awards

1. Select the agency after checking its identity and hierarchy.
2. Read `programs` with `filters={"agency_id":"RETURNED_ORGANIZATION_UUID"}`.
3. Read the full `awards` dataset with `awarding_agency_id`, `funding_agency_id`
   or `awarding_office_id`, depending on the question.
4. For published aggregate rows, use `agency-summary-totals` and
   `agency-award-summaries` with `organization_id`.

Awarding and funding agencies are distinct. Agency codes in baseline summary
collections are not organization UUIDs. Use the schema's code field when querying
summaries, and do not turn codes into UUIDs or match departments by fuzzy names.