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

# Make your first request

This walkthrough finds an organization and retrieves its full published record.
Use a server, terminal or private development environment.

## 1. Create a key

[Create a DefDex account](https://app.defdex.io/auth/sign-up), verify your email,
and open [API keys](https://app.defdex.io/developer/keys). Create a key with
`data:read`. Copy the value when it is shown; it is displayed only once.

Load it privately into the `DEFDEX_API_KEY` environment variable. Do not put it in
a URL, source file, screenshot or browser bundle. The examples below read that
variable and never contain a real key.

## 2. Find an organization

```sh
curl --fail-with-body --get \
  'https://app.defdex.io/api/v1/datasets/organizations' \
  --header "Authorization: Bearer $DEFDEX_API_KEY" \
  --header 'Accept: application/json' \
  --data-urlencode 'q=Anduril' \
  --data-urlencode 'limit=5'
```

Search is case-insensitive substring matching. Compare the returned name, website,
country and identifiers before selecting a match; search does not resolve identity.
An empty `data` array is a successful query with no matches.

A list response has this shape (values below are illustrative):

```json
{
  "data": [{
    "record_id": "OPAQUE_RETURNED_RECORD_ID",
    "attributes": {
      "id": "00000000-0000-0000-0000-000000000001",
      "name": "Example organization",
      "type": "company",
      "website": null
    }
  }],
  "next_cursor": null,
  "build_id": "EXAMPLE_BUILD"
}
```

Actual attributes follow the [organization reference](/api-reference/organizations-and-agencies/list-organizations-records).
Do not copy the placeholder ID into a real lookup.

## 3. Retrieve the exact record

Use `record_id` from the response, encoded as one URL segment:

```python
from defdex import DefDexClient

api = DefDexClient()  # reads DEFDEX_API_KEY
page = api.list("organizations", q="Anduril", limit=5)
if page["data"]:
    match = page["data"][0]  # inspect identity before using a match in production
    detail = api.get("organizations", match["record_id"])
    print(detail["data"]["attributes"]["name"])
```

Install the Python client using the [client guide](/sdks-and-cli).
`attributes.id` is the entity UUID used in relationship filters. `record_id` is the
opaque lookup identifier used by `GET /datasets/{dataset}/{record_id}`. They are
different values. Website slugs are another identifier; use an exact `slug` filter
to resolve one.

## 4. Continue your workflow

Read [agencies](/agencies), [programs](/programs) or [awards](/awards). To discover
all collections and allowed fields, call `GET /datasets`. To read more than one
page, follow [pagination](/published-datasets-and-pagination).

On an error, inspect the status, JSON `error` and `X-Request-Id`; see
[errors and retries](/errors). Avoid cURL verbose output when sharing diagnostics:
it can include the authorization header.