northstar-sdk

Python client for the Northstar platform API. It authenticates with the API key of an integration (developer) account and talks only to the platform's Next.js API (NORTHSTAR_API_URL), never to a database or a warehouse.

Install

pip install northstar-sdk
# or
uv add northstar-sdk

Configure

Example

from northstar_sdk import Client

client = Client()

orders = client.datasets.upsert(
    location={"schema": "marts", "table": "orders"},
    name="Orders",
    type="TABLE",
    layer="GOLD",
    storage_system_slug="warehouse",
)
orders.assign_to_team("sales")
orders.analyze()

Documentation

The user guide is the Developers section of the platform's help center (Help, in the app). Its source is in this repository:

• Integration accounts
• API keys
• Python SDK: configuration, namespaces, write methods, governance, errors
• SDK recipes: warehouses, datasets, documents, KPIs, dashboards, pipelines
• SDK reference: credentials, locations, errors, raw HTTP

A change to the SDK's public behaviour updates those articles, in English and French, in the same change (see the root CLAUDE.md).

Maintaining the SDK

The SDK is a thin HTTP client: request bodies are validated by the servers, not by the SDK.

flowchart LR
  Sdk["northstar-sdk Client"]
  Bff["Next.js /api/feature/..."]
  FastApi["FastAPI /v1/feature/..."]
  Compute["northstar-compute"]
  Prisma["Prisma / Postgres"]
  Sdk -->|"X-API-KEY"| Bff
  Bff -->|"proxyAuthenticatedJson"| FastApi
  FastApi --> Compute
  Bff --> Prisma

• Storage credentials are checked in warehouse/credentials.py (validate_and_normalize_credentials).
• Dataset and collection location keys: LOCATION_KEY_PARTS in datasets/location.py and document_collections/location.py.
• Resources proxied to FastAPI use snake_case JSON; Next.js catalogue resources (kpi-catalogue, dashboards, figures) use camelCase. The SDK maps snake_case Python arguments for you.

When you change a FastAPI *WriteRequest or a Next.js Zod schema:

1. Update the matching handle _payload() / _base_payload() in src/northstar_sdk/handles/.
2. Update the namespace arguments and src/northstar_sdk/types/params.py.
3. Run uv run --package northstar-sdk pytest tests/test_typing_params.py.
4. Update the SDK articles of the help center (front/content/help/*/python-sdk.md, sdk-recipes.md, sdk-reference.md).

Publishing: PUBLISHING.md.