Dalea SDK

The Dalea SDK is one public API contract shipped as two official clients — @dalea/sdk (TypeScript/JavaScript) and dalea (Python). Both are generated from the same public OpenAPI subset, so they stay in lockstep: the same operations, the same request/response shapes, mirrored method names (listEnvironments in TS is list_environments in Python).

This page covers the concepts shared by both SDKs. For runnable, per-language code, go straight to the language pages — and every operation in the API reference carries a ready-to-copy SDK example in both languages.

What the SDK covers

The SDK exposes the public, programmatically-accessible surface of the platform — five domains:

client.data

The data platform: environments, tables, columns, objects, the query engine, saved queries, result batches, schema validation, naming schemes, and import mappings.

client.documents

Document metadata (list, create, get, update) plus the markdown round-trip — read a document as markdown, append/insert/update/replace blocks.

client.inventory

Lab inventory: item types & lots, the container hierarchy, placements (check-in/out, move), consumption & quantity adjustment, and audit trails. Reads plus the operational writes instrument integrations drive — type/schema management stays in-app.

client.search

Unified search across documents, files, data objects, and result schemas — filterable by type, environment, project, table(s), author, and date, with offset pagination.

client.storage

Files: uploads (multipart & base64), metadata, short-lived presigned download URLs, and storage-usage breakdowns.

Lifecycle is reversible everywhere: entities are archived and restored, never hard-deleted.

Install

npm install @dalea/sdk

@dalea/sdk runs in Node ≥ 20, browsers, and edge runtimes (ESM + CJS, zero runtime dependencies). dalea needs Python 3.11+ and ships sync + async clients over a pooled httpx transport.

Authentication model

Both SDKs resolve auth the same way: an explicit credential → an explicit API key → (TS only) the session cookie → the DALEA_API_KEY environment variable. In a server script, set DALEA_API_KEY and construct a bare client — it just works.

ApiKeyCredential

A workspace-scoped dalea_… key (Settings → Security → API keys). The default for first-party scripts and backends.

OAuthPkceCredential

Third-party apps acting on behalf of a user — OAuth 2.1 + PKCE, with automatic token refresh on 401.

OAuthClientCredentialsCredential

Machine-to-machine — the client-credentials grant for services acting as themselves.

SessionCookieCredential (TS only)

First-party browser apps, same-origin — reuses the logged-in session cookie.

See Authentication for obtaining each credential, and the language pages for the construction code.

Workspace context

Every call resolves to a workspace. API keys and OAuth credentials are bound to their workspace when created, so those callers need no extra scoping — a bare client just works. For credentials that don't pin a workspace (chiefly the first-party session cookie), the client sends an X-Workspace header: set a default at construction, change it later (setWorkspace / set_workspace), or override it per call — the per-call value always wins.

Pagination

List methods return one page, keyed by the resource name (for example { environments: [...] } or { objects: [...], total, limit, offset }). Each listing surface also has an iterate* companion that walks every item across pages — an async iterator in TypeScript, a generator in Python (sync on DaleaClient, async on AsyncDaleaClient) — so you never manage cursors or offsets yourself.

Retries and errors

Non-2xx responses map to a typed error hierarchy (DaleaError and subclasses like DaleaNotFoundError, DaleaValidationError, DaleaRateLimitError). Throttling (429) and transient 503s are retried automatically with exponential backoff + jitter honoring Retry-After — writes included, since a throttle is rejected before the handler runs so replaying is safe. A rate-limit error surfaces only once retries are exhausted; retry counts, delays, and write-retry behavior are tunable per client.

Contract parity

Both SDKs — and the API reference — are generated from the same public OpenAPI document, and CI fails if either client drifts from the contract. That has a practical upside: browse any operation in the reference, and copy its @dalea/sdk or dalea snippet straight into your code.

Next