# cognitedata/cognite-sdk-python architecture

> Architecture diagram of the GitHub repository cognitedata/cognite-sdk-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cognitedata/cognite-sdk-python
- Repository: https://github.com/cognitedata/cognite-sdk-python

## Overview

The Cognite Python SDK lets developers and data scientists call Cognite Data Fusion (CDF) from Python. The principal workflow is to construct a client, invoke a domain API, send requests through shared asynchronous API and HTTP layers, and receive Python resource objects or errors. The README documents both native async use and a synchronous client that wraps the async client. The graph groups major API capabilities and shared runtime layers; several domain APIs are represented by their exact enclosing directories because their individual implementations were not sampled.

Main entry points: [`cognite/client/_api_client.py`](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_api_client.py) (API operations), [`cognite/client/_cognite_client.py`](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_cognite_client.py) (Async client), [`cognite/client/_basic_api_client.py`](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_basic_api_client.py) (HTTP API base), [`cognite/client/_sync_cognite_client.py`](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_sync_cognite_client.py) (Sync client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entry points"]
  node_async_client["Async client<br/>[_cognite_client.py]"]
  node_sync_client["Sync client"]
end

subgraph group_domains["CDF domain APIs"]
  node_timeseries["Time series and datapoints"]
  node_modeling["Data modeling"]
  node_files_docs["Files and documents"]
  node_transformations["Transformations"]
  node_workflows["Workflows"]
  node_iam_raw["IAM and Raw"]
end

subgraph group_runtime["Request runtime"]
  node_api_client["API operations<br/>[_api_client.py]"]
  node_basic_client["HTTP API base"]
  node_http["HTTP transport<br/>[_http_client.py]"]
end

subgraph group_models["Data and results"]
  node_resource_models["Resource models<br/>[_base.py]"]
  node_datapoint_models["Datapoint models<br/>[datapoints.py]"]
  node_filter_models["Query filters<br/>[filters.py]"]
  node_iam_models["IAM models<br/>[iam.py]"]
  node_workflow_models["Workflow models<br/>[workflows.py]"]
  node_response["HTTP responses<br/>[response.py]"]
end

subgraph group_support["Runtime support"]
  node_config["Client configuration<br/>[config.py]"]
  node_errors["SDK errors<br/>[exceptions.py]"]
  node_constants["SDK constants<br/>[_constants.py]"]
  node_async_helpers["Async helpers<br/>[_async_helpers.py]"]
  node_concurrency["Concurrency<br/>[_concurrency.py]"]
  node_auxiliary["Shared utilities<br/>[_auxiliary.py]"]
  node_identifier["Identifiers<br/>[_identifier.py]"]
  node_json["JSON conversion<br/>[_json_extended.py]"]
  node_text["Text utilities<br/>[_text.py]"]
end

node_developer(("SDK user"))

node_developer -->|"creates"| node_async_client
node_developer -->|"creates"| node_sync_client
node_async_client -->|"exposes APIs"| node_timeseries
node_async_client -->|"exposes APIs"| node_modeling
node_async_client -->|"exposes APIs"| node_files_docs
node_async_client -->|"exposes APIs"| node_transformations
node_async_client -->|"exposes APIs"| node_workflows
node_async_client -->|"exposes APIs"| node_iam_raw
node_sync_client -->|"wraps"| node_async_client
node_sync_client -->|"runs synchronously"| node_async_helpers
node_timeseries -.->|"uses operations"| node_api_client
node_modeling -.->|"uses operations"| node_api_client
node_files_docs -->|"uses operations"| node_api_client
node_transformations -.->|"uses operations"| node_api_client
node_workflows -->|"uses operations"| node_api_client
node_iam_raw -->|"uses operations"| node_api_client
node_api_client -->|"delegates requests"| node_basic_client
node_api_client -->|"loads resources"| node_resource_models
node_api_client -->|"uses filters"| node_filter_models
node_api_client -->|"raises errors"| node_errors
node_api_client -->|"uses helpers"| node_auxiliary
node_api_client -->|"coordinates tasks"| node_concurrency
node_api_client -->|"uses identifiers"| node_identifier
node_api_client -->|"uses text helpers"| node_text
node_basic_client -->|"sends requests"| node_http
node_basic_client -->|"reads settings"| node_config
node_basic_client -->|"builds responses"| node_response
node_basic_client -->|"handles errors"| node_errors
node_basic_client -->|"converts JSON"| node_json
node_async_helpers -->|"uses executor"| node_concurrency
node_auxiliary -->|"converts resources"| node_resource_models
node_auxiliary -->|"unpacks responses"| node_response
node_timeseries -.->|"uses models"| node_datapoint_models
node_iam_raw -->|"uses models"| node_iam_models
node_workflows -->|"uses models"| node_workflow_models

click node_async_client "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_cognite_client.py"
click node_sync_client "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_sync_cognite_client.py"
click node_timeseries "https://github.com/cognitedata/cognite-sdk-python/tree/master/cognite/client/_api"
click node_modeling "https://github.com/cognitedata/cognite-sdk-python/tree/master/cognite/client/_api/data_modeling"
click node_files_docs "https://github.com/cognitedata/cognite-sdk-python/tree/master/cognite/client/_api"
click node_transformations "https://github.com/cognitedata/cognite-sdk-python/tree/master/cognite/client/_api/transformations"
click node_workflows "https://github.com/cognitedata/cognite-sdk-python/tree/master/cognite/client/_api/workflows"
click node_iam_raw "https://github.com/cognitedata/cognite-sdk-python/tree/master/cognite/client/_api"
click node_api_client "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_api_client.py"
click node_basic_client "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_basic_api_client.py"
click node_http "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_http_client.py"
click node_config "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/config.py"
click node_resource_models "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/data_classes/_base.py"
click node_datapoint_models "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/data_classes/datapoints.py"
click node_filter_models "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/data_classes/filters.py"
click node_iam_models "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/data_classes/iam.py"
click node_workflow_models "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/data_classes/workflows.py"
click node_response "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/response.py"
click node_errors "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/exceptions.py"
click node_constants "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_constants.py"
click node_async_helpers "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/utils/_async_helpers.py"
click node_concurrency "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/utils/_concurrency.py"
click node_auxiliary "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/utils/_auxiliary.py"
click node_identifier "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/utils/_identifier.py"
click node_json "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/utils/_json_extended.py"
click node_text "https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/utils/_text.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_async_client,node_sync_client,node_developer toneBlue
class node_timeseries,node_modeling,node_files_docs,node_transformations,node_workflows,node_iam_raw toneAmber
class node_api_client,node_basic_client,node_http toneMint
class node_resource_models,node_datapoint_models,node_filter_models,node_iam_models,node_workflow_models,node_response toneRose
class node_config,node_errors,node_constants,node_async_helpers,node_concurrency,node_auxiliary,node_identifier,node_json,node_text toneIndigo
```

## Components

### Client entry points

- [Async client](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_cognite_client.py): `cognite/client/_cognite_client.py`
- [Sync client](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_sync_cognite_client.py): `cognite/client/_sync_cognite_client.py`

### CDF domain APIs

- [Time series and datapoints](https://github.com/cognitedata/cognite-sdk-python/tree/master/cognite/client/_api): `cognite/client/_api`
- [Data modeling](https://github.com/cognitedata/cognite-sdk-python/tree/master/cognite/client/_api/data_modeling): `cognite/client/_api/data_modeling`
- [Files and documents](https://github.com/cognitedata/cognite-sdk-python/tree/master/cognite/client/_api): `cognite/client/_api`
- [Transformations](https://github.com/cognitedata/cognite-sdk-python/tree/master/cognite/client/_api/transformations): `cognite/client/_api/transformations`
- [Workflows](https://github.com/cognitedata/cognite-sdk-python/tree/master/cognite/client/_api/workflows): `cognite/client/_api/workflows`
- [IAM and Raw](https://github.com/cognitedata/cognite-sdk-python/tree/master/cognite/client/_api): `cognite/client/_api`

### Request runtime

- [API operations](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_api_client.py): `cognite/client/_api_client.py`
- [HTTP API base](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_basic_api_client.py): `cognite/client/_basic_api_client.py`
- [HTTP transport](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_http_client.py): `cognite/client/_http_client.py`

### Data and results

- [Resource models](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/data_classes/_base.py): `cognite/client/data_classes/_base.py`
- [Datapoint models](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/data_classes/datapoints.py): `cognite/client/data_classes/datapoints.py`
- [Query filters](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/data_classes/filters.py): `cognite/client/data_classes/filters.py`
- [IAM models](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/data_classes/iam.py): `cognite/client/data_classes/iam.py`
- [Workflow models](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/data_classes/workflows.py): `cognite/client/data_classes/workflows.py`
- [HTTP responses](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/response.py): `cognite/client/response.py`

### Runtime support

- [Client configuration](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/config.py): `cognite/client/config.py`
- [SDK errors](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/exceptions.py): `cognite/client/exceptions.py`
- [SDK constants](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/_constants.py): `cognite/client/_constants.py`
- [Async helpers](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/utils/_async_helpers.py): `cognite/client/utils/_async_helpers.py`
- [Concurrency](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/utils/_concurrency.py): `cognite/client/utils/_concurrency.py`
- [Shared utilities](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/utils/_auxiliary.py): `cognite/client/utils/_auxiliary.py`
- [Identifiers](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/utils/_identifier.py): `cognite/client/utils/_identifier.py`
- [JSON conversion](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/utils/_json_extended.py): `cognite/client/utils/_json_extended.py`
- [Text utilities](https://github.com/cognitedata/cognite-sdk-python/blob/master/cognite/client/utils/_text.py): `cognite/client/utils/_text.py`

### Other components

- **SDK user**

## Connections

- SDK user → Async client: creates (evidence: `README.md`)
- SDK user → Sync client: creates (evidence: `README.md`)
- Async client → Time series and datapoints: exposes APIs (evidence: `cognite/client/_cognite_client.py`)
- Async client → Data modeling: exposes APIs (evidence: `cognite/client/_cognite_client.py`)
- Async client → Files and documents: exposes APIs (evidence: `cognite/client/_cognite_client.py`)
- Async client → Transformations: exposes APIs (evidence: `cognite/client/_cognite_client.py`)
- Async client → Workflows: exposes APIs (evidence: `cognite/client/_cognite_client.py`)
- Async client → IAM and Raw: exposes APIs (evidence: `cognite/client/_cognite_client.py`)
- Sync client → Async client: wraps (evidence: `README.md`)
- Sync client → Async helpers: runs synchronously (evidence: `cognite/client/_sync_cognite_client.py`)
- Time series and datapoints → API operations: uses operations (evidence: `cognite/client/_api/raw/databases.py`)
- Data modeling → API operations: uses operations
- Files and documents → API operations: uses operations (evidence: `cognite/client/_api/document_preview.py`)
- Transformations → API operations: uses operations
- Workflows → API operations: uses operations (evidence: `cognite/client/_api/workflows/tasks.py`)
- IAM and Raw → API operations: uses operations (evidence: `cognite/client/_api/raw/databases.py`)
- API operations → HTTP API base: delegates requests (evidence: `cognite/client/_api_client.py`)
- API operations → Resource models: loads resources (evidence: `cognite/client/_api_client.py`)
- API operations → Query filters: uses filters (evidence: `cognite/client/_api_client.py`)
- API operations → SDK errors: raises errors (evidence: `cognite/client/_api_client.py`)
- API operations → Shared utilities: uses helpers (evidence: `cognite/client/_api_client.py`)
- API operations → Concurrency: coordinates tasks (evidence: `cognite/client/_api_client.py`)
- API operations → Identifiers: uses identifiers (evidence: `cognite/client/_api_client.py`)
- API operations → Text utilities: uses text helpers (evidence: `cognite/client/_api_client.py`)
- HTTP API base → HTTP transport: sends requests (evidence: `cognite/client/_basic_api_client.py`)
- HTTP API base → Client configuration: reads settings (evidence: `cognite/client/_basic_api_client.py`)
- HTTP API base → HTTP responses: builds responses (evidence: `cognite/client/_basic_api_client.py`)
- HTTP API base → SDK errors: handles errors (evidence: `cognite/client/_basic_api_client.py`)
- HTTP API base → JSON conversion: converts JSON (evidence: `cognite/client/_basic_api_client.py`)
- Async helpers → Concurrency: uses executor (evidence: `cognite/client/utils/_async_helpers.py`)
- Shared utilities → Resource models: converts resources (evidence: `cognite/client/utils/_auxiliary.py`)
- Shared utilities → HTTP responses: unpacks responses (evidence: `cognite/client/utils/_auxiliary.py`)
- Time series and datapoints → Datapoint models: uses models (evidence: `cognite/client/_api/datapoint_tasks.py`)
- IAM and Raw → IAM models: uses models (evidence: `cognite/client/_api/iam/sessions.py`)
- Workflows → Workflow models: uses models (evidence: `cognite/client/_api/workflows/tasks.py`)
