Docs menu
SDK reference
Credentials by storage kind, location keys, errors and raw HTTP calls.
In short
This page lists what the SDK sends for each kind of resource: storage credentials, dataset and collection locations. It also describes the error answers, and how to call the platform API without the SDK. For the concepts, start with Python SDK.
Credentials by storage kind
client.storage_systems.create(…, kind=…, credentials={…}) expects these fields. Credentials are encrypted before they are stored and never returned.
| Kind | Required | Optional |
|---|---|---|
POSTGRESQL | host, user, password, database | port (default 5432) |
MYSQL | host, user, password, database | port (default 3306) |
CLICKHOUSE | host, user, database | password, port, secure, interface (http or native) |
SNOWFLAKE | account, user, database, and password or private_key | warehouse, role, schema |
REDSHIFT | host, user, password, database | port (default 5439), ssl (default true) |
DATABRICKS | server_hostname, http_path, access_token | catalog, schema |
BIGQUERY | client_email, private_key, project_id | the other fields of the service account file |
FABRIC | server, database, tenant_id, client_id, client_secret | — |
S3 | access_key_id, secret_access_key | region (default us-east-1), endpoint_url, bucket, session_token |
GOOGLE_DRIVE | client_email, private_key | the other fields of the service account file |
ONEDRIVE | tenant_id, client_id, client_secret | — |
SHAREPOINT | tenant_id, client_id, client_secret, and site_id or site_url | — |
For Google service accounts, parse the JSON file in your code and send its fields. A whole file passed as one value (service_account or service_account_json) is rejected.
A missing required field fails with a 400 answer that names the missing fields.
Dataset locations
location tells where the table or file is. Its keys depend on the kind of the storage system:
| Kind | location keys |
|---|---|
POSTGRESQL, MYSQL, REDSHIFT, FABRIC | schema, table |
CLICKHOUSE | database, table |
SNOWFLAKE | database, schema, table |
DATABRICKS | catalog, schema, table |
BIGQUERY | project, dataset, table |
S3 | bucket, key, and optionally format: csv, tsv or parquet |
GOOGLE_DRIVE | folderId, fileId |
ONEDRIVE | driveId, folderId, fileId |
SHAREPOINT | siteId, driveId, folderId, fileId |
On Microsoft Fabric, add database for a table outside the connection's database.
The storage system and the location identify a dataset: upsert with the same pair updates the existing dataset. type is TABLE, VIEW or MATERIALIZED_VIEW.
Collection locations
| Kind | location keys |
|---|---|
GOOGLE_DRIVE | folderId (folder_id is accepted). For a shared drive, also driveId. |
S3 | bucket, prefix |
ONEDRIVE | driveId, folderId |
SHAREPOINT | siteId, driveId, folderId |
A collection is identified by its slug, and by its storage system and location. create fails with 409 if either already exists. upsert updates the matching collection, and fails with 409 if the slug and the location point to two different collections.
Error answers
| Status | Meaning | Body |
|---|---|---|
400 | Invalid input | {"error": "invalid_input", "message": "…"} |
401 | Missing, unknown or revoked key | {"error": "Unauthorized"} |
403 | The account lacks the feature or the right on the resource | {"error": "Forbidden"} |
404 | The resource does not exist, or the account cannot see it | {"error": "…"} |
409 | create on a business key that already exists | {"error": "conflict", "message": "…", "detail": {"existing_id": "…", "conflict_key": "slug"}} |
The SDK raises PermissionError on 401 and httpx.HTTPStatusError on the others; error.response.json() gives the body.
Raw HTTP calls
The SDK is the supported way to integrate. If you cannot use Python, call the same API: the base address is your NORTHSTAR_API_URL, and every request carries the key.
curl -H "X-API-KEY: $NORTHSTAR_API_KEY" "$NORTHSTAR_API_URL/me"GET /me returns the account and its organization: use it to check a key. The main write calls, relative to the base address:
| Call | Method and path |
|---|---|
| Storage system | POST /feature/data-storage-systems/create or /upsert |
| Dataset | POST /feature/datasets/create or /upsert |
| Dataset analysis | POST /feature/datasets/{id}/analysis/run |
| Document collection | POST /feature/document-collections/create or /upsert, then /ingest |
| Data source | POST /feature/data-sources/create or /upsert |
| KPI | POST /feature/kpi-catalogue |
| Dashboard | POST /feature/dashboards |
Bodies use the SDK's argument names in snake_case, plus organization_id, which the SDK reads from GET /me. KPI and dashboard bodies use camelCase (datasetId, embedUrl). These paths can change between versions; the SDK follows them for you.
FAQ
Where do I find the folder id of a Drive folder?
In the folder's URL: it is the part after /folders/.
Can I register a CSV file as a dataset?
Yes, from Amazon S3 with format="csv", or from a drive with its fileId.
Is there an OpenAPI description of this API? Not for integrators: the SDK and this page are the reference.