Dalux Build API – Python Client

A lightweight Python client for the Dalux Build REST API.

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