Dalux Build API – Python Client

A lightweight Python client for the Dalux Build REST API.

[!IMPORTANT] This is an unofficial client, not affiliated with or endorsed by Dalux ApS. It provides no API access or credentials. You must use your own authorized Dalux subscription and API key within your agreement with Dalux. The MIT license covers this client code only; it does not grant rights to Dalux's API or Services. Commercial or hosted use requires authorization under your own Dalux agreement. See the Legal and Usage Notice.

See the Node.js client (dalux-build-api) and the webhook server built on this package — the two clients are versioned, tested, and released together; see ../CONTRIBUTING.md. For running the scheduled outbound webhook monitor embedded in a script via dalux.webhook_server, see docs/webhook_server.md.

Requirements

• Python 3.10 or later
• requests ≥ 2.28

Installation

pip install dalux-build

Getting Started

from dalux_build import create_client

dalux = create_client(
    base_url="https://<your-company>.dalux.com/api",
    api_key="YOUR_API_KEY",
    project_id="my-project-id",  # optional: see "Client-level defaults" below
)

The returned DaluxClient object exposes one attribute per API resource group (see API Reference below).

Examples

List all projects

projects = dalux.projects.list_projects()
print(projects)  # list[Project] — pass full_response=True for the full ProjectsListResponse

Get a specific project

project = dalux.projects.get_project(project_id="my-project-id")
print(project)

List tasks on a project

tasks = dalux.tasks.get_project_tasks(
    params={"updatedAfter": "2024-01-01"},
    project_id="my-project-id",
)
print(tasks)

Local dashboards

Install the optional Streamlit and Plotly dependencies:

pip install "dalux-build[dashboard]"

Every API namespace exposes the same resource-scoped dashboard() method. The first built-in template is the task lifecycle timeline:

dashboard = dalux.tasks.dashboard(
    template="task-timeline",
    template_options={
        "timezone": "Europe/Copenhagen",
        "task_params": {"typeId": "my-task-type-id"},
    },
)

print(dashboard.url)
dashboard.stop()

The call starts a local Streamlit process, opens it in the default browser, and returns a DashboardHandle. Pass open_browser=False to start without opening a tab, or port=8501 to select a port. The process uses the client's configured project by default; pass template_options={"project_id": "another-project"} to override it.

Templates are scoped to their owning API. For example, dalux.files.dashboard(...) and dalux.folders.dashboard(...) are available for future file and folder templates, but reject task-timeline. Inspect dalux.files.available_dashboards to discover templates registered for that namespace.

Upload a file (chunked)

# 1. Create an upload slot
upload = dalux.file_upload.create_upload(
    {"fileName": "drawing.pdf", "mimeType": "application/pdf"},
    project_id="my-project-id",
    file_area_id="my-file-area-id",
)
upload_guid = upload["uploadGuid"]

# 2. Upload the file content
with open("drawing.pdf", "rb") as f:
    dalux.file_upload.upload_file_part(
        upload_guid, f.read(), project_id="my-project-id", file_area_id="my-file-area-id"
    )

# 3. Finalize
result = dalux.file_upload.finish_upload(
    upload_guid,
    {"folderId": "target-folder-id"},
    project_id="my-project-id",
    file_area_id="my-file-area-id",
)
print("New file ID:", result["fileId"])

Client-level defaults (project_id / file_area_id)

Most methods take project_id (and, where relevant, file_area_id) as a keyword-only argument. If you mostly work against a single project, set a default once on the client and omit it everywhere else:

dalux = create_client(
    base_url="https://<your-company>.dalux.com/api",
    api_key="YOUR_API_KEY",
    project_id="my-project-id",  # or set DALUX_PROJECT_ID
    file_area_id="my-file-area-id",  # or set DALUX_FILE_AREA_ID
)

dalux.tasks.get_project_tasks()  # uses the default project_id
dalux.files.get_files()  # uses the default project_id + file_area_id
dalux.tasks.get_project_tasks(project_id="other-project-id")  # explicit value wins

An explicit project_id/file_area_id passed to a call always overrides the client default; a ValidationError is raised if neither is available.

full_response

Single-page list methods (list_projects, list_files, …) default to returning just the plain list[...] of items. Pass full_response=True to get the full response model instead, which also exposes .metadata (pagination info) and .links:

files = dalux.files.get_files(project_id="p1", file_area_id="fa1")  # list[File]
# Note: get_files() paginates automatically; for single-page results, use list_files()

response = dalux.files.list_files(project_id="p1", file_area_id="fa1", full_response=True)
response.items  # same list[File]
response.metadata  # Metadata(total_items=..., total_remaining_items=...)
response.links  # pagination links

to_dataframe

The same list/collection methods also accept to_dataframe=True, returning the items flattened into a pandas DataFrame directly — nested objects are flattened into ::-separated column names (e.g. owner::userId). Requires pandas to be installed (pip install pandas); takes precedence over full_response if both are passed.

df = dalux.tasks.get_project_tasks(project_id="p1", to_dataframe=True)
df.columns  # e.g. Index(['taskId', 'title', 'type::typeId', 'type::name', ...])

# Equivalent to, but shorter than:
response = dalux.tasks.get_project_tasks(project_id="p1", full_response=True)
df = response.to_dataframe() if response else pd.DataFrame()

The primary paginated methods (get_files, get_folders, get_project_tasks, list_inspection_plans, …) automatically follow pagination and accept to_dataframe=True too — they have no full_response mode (they return a bare list already), but flatten the same way:

df = dalux.files.get_files(project_id="p1", file_area_id="fa1", to_dataframe=True)

Authentication

Every request automatically includes the X-API-KEY header with the API key supplied to create_client. No additional configuration is required.

API keys are managed in the Dalux Build UI under Settings › Integrations › API Identities. Contact support@dalux.com to activate API access for your company profile.

Error Handling

All methods raise requests.HTTPError on 4xx / 5xx responses:

import requests

try:
    project = dalux.projects.get_project(project_id="unknown-id")
except requests.HTTPError as exc:
    print(exc.response.status_code, exc.response.json())

API Reference

project_id and file_area_id are keyword-only in every method below (e.g. get_task(task_id, *, project_id=None)) and fall back to the client's configured default when omitted — see Client-level defaults. List methods additionally accept full_response=False (see full_response) and to_dataframe=False (see to_dataframe) — omitted from the signatures below for brevity.

ProjectsApi

CompaniesApi

CompanyCatalogApi

Account-level (not project-scoped) — no project_id.

TasksApi

FileAreasApi

FilesApi

Browse (get_files, get_files_in_folder, …) uses GET /6.1/projects/{projectId}/file_areas/{fileAreaId}/files with automatic pagination. Single-page access via list_files. get_file uses 5.0 for a single file id (Dalux Build API 4.14).

bulk_download_files' own file_area_id parameter is the exception: passing None there selects path-based resolution and is intentionally not backfilled from the client default.

FoldersApi

FileUploadApi

FileRevisionsApi

FormsApi

UsersApi

ProjectTemplatesApi

InspectionPlansApi

TestPlansApi

VersionSetsApi

WorkPackagesApi

Advanced Usage

Using individual API classes directly

from dalux_build.configuration import Configuration
from dalux_build.api_client import ApiClient
from dalux_build.api import ProjectsApi, TasksApi

config = Configuration(
    base_url="https://<company>.dalux.com/api",
    api_key="YOUR_API_KEY",
)
api_client = ApiClient(config)

projects = ProjectsApi(api_client)
tasks = TasksApi(api_client)

Testing

cd python
pip install -e ".[dev,webhook]"
pytest --cov=dalux_build --cov-report=term-missing

CI runs this on Python 3.11 and 3.13, plus the webhook server's own tests against this checkout's editable install (not the published PyPI package) — see ../.github/workflows/tests.yml.

Releasing

This package is versioned and published together with the Node.js client by Changesets — there is no manual edit of version in pyproject.toml, and nothing publishes to PyPI unless the full test suite (Node.js, Python, webhook server) passes first. See ../CONTRIBUTING.md for the full flow and ../README.md for the npm side of it.

License

MIT