> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cognite API introduction

> How to call the Cognite Data Fusion REST API: URLs, calendar versioning, Postman, pagination, and throttling.

<Warning>
  Untitled `oneOf` schemas appear here as "Option 1", "Option 2", etc.

  For Documents, `/documents/search`, `/documents/passages/search`, and `/documents/aggregate` may show raw `$ref` text in descriptions.

  Use the Cognite API reference at [https://api-docs.cognite.com/20230101/](https://api-docs.cognite.com/20230101/) for clearer labels and full text until we have fixed the upstream OpenAPI.
</Warning>

## OpenAPI downloads

<Note>
  You can download the OpenAPI specification as JSON to quickly get started with API exploration and testing:

  * [Download OpenAPI (20230101)](https://storage.googleapis.com/cognitedata-api-docs/dist/20230101.json)
  * [Download OpenAPI (20230101-beta)](https://storage.googleapis.com/cognitedata-api-docs/dist/20230101-beta.json)
  * [Download OpenAPI (20230101-alpha)](https://storage.googleapis.com/cognitedata-api-docs/dist/20230101-alpha.json)
</Note>

## Request URLs

CDF exposes a RESTful API. Requests use a URL of this form:

```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
https://api.cognitedata.com/api/{version}/projects/{project}/{resource}
```

* **`{version}`** — Path API version (stable REST APIs use `v1`). See [API versions](#api-versions).
* **`{project}`** — Project identifier for the resources you are accessing.
* **`{resource}`** — Resource type (for example `assets`, `files`, `events`). Add query parameters or path segments as documented for each endpoint.

For HTTP methods (GET, POST, and so on), standard operation patterns (create, list, filter, retrieve, and so on), projects, and resource types, see [Use the API](/dev/use_the_API).

<Tip>
  Cluster base URLs and current multi-tenant IP addresses for allowlisting outbound traffic are listed under [IP addresses for the API](/dev/use_the_API#ip-addresses-for-the-api) in **Use the API**.
</Tip>

## API versions

All stable Cognite REST APIs use the **`v1`** path prefix. Within `v1`, behavior is pinned with **calendar versions**: dates in the form `YYYYMMDD` passed in the **`Cdf-Version`** request header.

To request a specific calendar version, set:

```http theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
Cdf-Version: <YYYYMMDD>
```

For example, `Cdf-Version: 20230205` selects API behavior as released on that date or earlier.

If you omit **`Cdf-Version`**, requests default to calendar version **`20230101`**, so existing clients keep working as new versions are released.

Breaking changes are shipped as new calendar versions; non-breaking changes apply across the API. For deprecation policy (including support for older versions after they are marked deprecated), removed legacy API versions, and detailed rules for backwards-compatible vs breaking changes, see [API versions](/dev/API_versioning).

### Beta versions

<Warning>
  We do not recommend beta versions for production environments.
</Warning>

Beta versions preview upcoming stable features. Request them with the **`Cdf-Version`** header using a date and the **`-beta`** suffix (for example, `Cdf-Version: 20230205-beta`). See [API versions](/dev/API_versioning#beta-versions) for SDK support and lifecycle.

### Alpha versions

<Warning>
  Alpha versions are experimental and may change or be removed at any time. They are indicated by an **`-alpha`** suffix (for example, `Cdf-Version: 20230101-alpha`). Use with caution.
</Warning>

## Using the Cognite API with Postman

<Steps>
  <Step title="Download the OpenAPI specification">
    Use the JSON download links in [OpenAPI downloads](#openapi-downloads) above.
  </Step>

  <Step title="Import into Postman">
    Open Postman and select **Import**. In the Import dialog box, drag and drop the downloaded file or folder, or use the file picker.
  </Step>

  <Step title="Configure import settings">
    In **View Import Settings**:

    * Set **Folder organization** to **Tags**
    * Turn off **Enable optional parameters**
    * Turn on **Always inherit authentication**
      Select **Import** to complete the process.
  </Step>

  <Step title="Set up authentication">
    Set the Authorization type to **Oauth2.0**. By default, settings are for Open Industrial Data. Visit [Cognite Hub](https://hub.cognite.com/open-industrial-data-211) to obtain credentials for use in Postman.

    <Note>
      **Open Industrial Data** is a public Cognite Data Fusion project with sample industrial data. You can use it to explore the API without your own CDF project or identity provider administrator access. For an overview, see [What is Open Industrial Data?](https://hub.cognite.com/open-industrial-data-211/what-is-open-industrial-data-994) on Cognite Hub.
    </Note>
  </Step>
</Steps>

<Tip>
  For more information, see [Getting Started with Postman](/dev/guides/postman/).
</Tip>

## Pagination

<Note>
  Most resource types support pagination, indicated by the `nextCursor` field in the response.
</Note>

To retrieve additional pages:

<Steps>
  <Step title="Check for nextCursor">
    If the response includes a `nextCursor`, more results are available.
  </Step>

  <Step title="Request the next page">
    Pass the value of `nextCursor` as the `cursor` parameter in your next request. All other parameters must remain the same.
  </Step>
</Steps>

For more detail on paging, see [Paging](/dev/concepts/pagination).

## Parallel retrieval

<Info>
  Parallel retrieval improves performance for complex queries by splitting data requests into multiple partitions.
</Info>

To use parallel retrieval:

<Steps>
  <Step title="Choose partition count">
    Decide how many partitions (`n`) to split the data set into (maximum 10 recommended).
  </Step>

  <Step title="Make parallel requests">
    For each partition `m` (from 1 to `n`), make a request to the endpoint (for example, `/events`) with the parameter `partition=m/n`.
  </Step>

  <Step title="Paginate within each partition">
    Follow the pagination process for each partition, passing the `partition` parameter to all subqueries.
  </Step>
</Steps>

<Warning>
  Processing parallel retrieval requests is subject to concurrency quota limits. If you exceed the limit, you will receive a `429` (Too Many Requests) response. Use at most 10 partitions to prevent issues. Some resources enforce this limit automatically.
</Warning>

<Note>
  For more details, see the `partition` attribute documentation for the specific CDF resource.
</Note>

## Request throttling

If you exceed your project's request capacity, CDF returns an HTTP `429` (Too Many Requests) status code. For rate and concurrency limits per API, throttling causes, and best practices for retry strategies, see [API rate limits](/api-reference/concepts/20230101/rate-limits).