> ## Documentation Index
> Fetch the complete documentation index at: https://developers.beta.dealroom.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with the Dealroom API in under 5 minutes. Obtain an access token, make your first request, and explore entity search results.

## Prerequisites

* A Dealroom API key. See [Authentication](/getting-started/authentication) to obtain one.
* An HTTP client (`curl`, Postman, or any language with an HTTP library).

## 1. Obtain an access token

Exchange your API key credentials for a Bearer token:

```bash theme={null}
curl -X POST https://accounts.beta.dealroom.co/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api-next.beta.dealroom.co",
    "grant_type": "client_credentials"
  }'
```

The response contains an `access_token` valid for `expires_in` seconds (typically 86400s / 24h).
Cache it and reuse it — do not request a new token per API call.

## 2. Query entities

Fetch the 10 highest-valued startups launched in 2020 or later:

```bash theme={null}
curl -g "https://api.beta.dealroom.app/data/entities?sort=-latest_valuation&limit=10&filter=launch_date[gte]:2020" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```

<Warning>
  Note the `-g` flag. curl treats `[` and `]` as glob ranges **even inside quotes**,
  so a filter expression without it fails before any request is sent:
  `curl: (3) bad range in URL`. `-g` (`--globoff`) turns globbing off. Other HTTP
  clients need nothing special — or percent-encode the brackets as `%5B` / `%5D`.
</Warning>

<Tip>
  The `X-Client-Id` header is **required** on all requests authenticated with an
  API key. See [Authentication](/getting-started/authentication) for details.
</Tip>

## 3. Understand the response

```json theme={null}
{
  "data": [
    {
      "uuid": "345d1ab6-33df-4759-9e17-0d0c0ec9ab1c",
      "name": "Example Corp",
      "type": "organization",
      "organization_subtype": "company",
      "launch_year": 2021,
      "hq_country": "United States",
      "hq_city": "San Francisco",
      "lat": 37.7878,
      "lon": -122.4032,
      "latest_valuation": {
        "value": 5000000000,
        "year": 2026,
        "month": 4
      },
      "tags": [
        { "id": 202, "name": "Artificial Intelligence", "type": "technology" }
      ]
    }
  ],
  "page": {
    "limit": 10,
    "offset": 0,
    "next_cursor": "eyJ2IjoxLCJkIjoibmV4dCIsInMiOiJfLmlkOmRlc2M...",
    "prev_cursor": null
  },
  "currency": "USD"
}
```

* `data` — array of matching entities. Entities are addressed by **`uuid`**; there is no numeric `id` on the entity. They expose flat HQ fields (`hq_country`, `hq_city`, `lat`, `lon`) and structured sub-objects like `latest_valuation` and `tags`. Monetary values are JSON numbers.
* `page.limit` / `page.offset` — the applied pagination params
* `page.total` — total matching records; only present when `include_total=true`
* `page.next_cursor` / `page.prev_cursor` — opaque cursors for keyset pagination; see [Pagination](/concepts/pagination)
* `currency` — the currency monetary fields are expressed in (defaults to `USD`; override with `?currency=EUR`)

Requests made **without** an API key additionally carry plan-cap metadata
(`page.capped`, `page.tier`, `page.ecosystem`) — API-key responses, like the one
above, omit those fields. See [Pagination](/concepts/pagination). Don't mark them
required in a schema-driven client.

<Note>
  Some fields are tier-gated: `latest_valuation` and `latest_revenue` are
  `premium`, and come back as `null` on lower tiers even when the underlying
  filter and sort still work. On keyless requests, `page.tier` shows the tier
  the request was served at.
</Note>

## 4. Paginate through results

Use `limit` and `offset` to page through results:

```bash theme={null}
# Page 2 (records 11-20)
curl -g "https://api.beta.dealroom.app/data/entities?sort=-latest_valuation&limit=10&offset=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: YOUR_CLIENT_ID"
```

For deep or sequential walks, prefer cursor pagination: round-trip
`page.next_cursor` via `?cursor=`, and **echo the same `sort` and `filter` on
every cursor request** — a cursor replayed without them returns
`400 Invalid cursor for this sort order; restart from the first page`.

See [Pagination](/concepts/pagination) for the full reference, including the
cursor rules and per-plan depth caps.

## Next steps

* Learn about [Filtering](/concepts/filtering) to narrow results with 65+ available filters.
* Explore [API Versioning](/concepts/versioning) to understand how breaking changes are handled.
* Browse the [API Reference](/api-reference) for all available endpoints.