Skip to documentation content
Dataset APIDocs

Synthetic datasets

Scope a synthetic-data pilot, read its dataset label, and integrate only an accepted delivery.

In this guide
  1. 1Define the intended use
  2. 2Pin the observed release
  3. 3Read the dataset label
  4. 4Integrate only an accepted release
In this guide
  1. 1Define the intended use
  2. 2Pin the observed release
  3. 3Read the dataset label
  4. 4Integrate only an accepted release

Product availability

Synthetic datasets are currently offered as scoped pilots and custom deliveries. The pilot starts from one immutable observed release, one intended use, a target volume, required fields, excluded identifiers, and jointly agreed acceptance criteria.

The API contract documents the intended delivery surface. Production access, thresholds, and recurring delivery are enabled only when they are included in the engagement scope.

Pilot journey

  1. 1
    State the decision, test, or analysis the data must support
  2. 2
    Pin the observed dataset and exact source release
  3. 3
    Agree the target row count, fields, constraints, and excluded identifiers
  4. 4
    Agree fidelity and privacy review criteria for the intended use
  5. 5
    Review the report and resolve any pending thresholds
  6. 6
    Publish for API or file delivery only after explicit acceptance

Illustrative vehicle-market scope

ItemIllustrative valueStatus
Observed referencedsv-preview-20260813 · 18,420 rowsAvailable reference
Target100,000 rows for testing and market analyticsPilot target
Fieldsmake, model, year, price, locationIn scope
FidelitySchema, distributions, coverage, relationshipsThreshold pending
PrivacyDirect identifiers and source-row similarityReview pending
DeliveryDataset API or fileNot published

Read the review before using the data

Fidelity is always relative to an intended use. A dataset that is adequate for pagination testing may not be adequate for market forecasting. Review field distributions, category coverage, relationships, missingness, rare combinations, and any domain-specific tests.

Privacy review must cover direct identifiers, similarity to source rows, rare records, and the impact of the intended use. Record the source release and review version with every downstream import.

Treat the dataset label as the delivery contract

Label fieldWhat to verify
Publication statusAccepted for the declared use; no required review remains pending
Observed source releaseExact immutable release used as the comparison point
Intended and approved usesYour integration stays inside the reviewed purpose
Prohibited usesDownstream teams cannot silently expand the purpose
Fidelity and privacy reviewReview version, thresholds, result, and unresolved limitations
Fields and volumeDelivered schema and row count match the accepted scope
Known limitationsRare combinations, tails, missingness, and domain caveats remain visible
ValidityWhich newer label or release supersedes this one

Use the standard released-dataset surface

After acceptance, a synthetic delivery is consumed through the same immutable dataset and release resources as an observed delivery. The delivery path does not require the customer to operate the synthesis process. Use the IDs supplied in the dashboard or handoff record; the example IDs below are placeholders until a release is accepted.

TaskOperationWhy
Inspect dataset and label contextGET /v1/datasets/{dataset_id}Confirm identity, fields, latest accepted release, and intended use
Inspect one immutable releaseGET /v1/datasets/{dataset_id}/releases/{release_id}Confirm quality, lineage, review state, and release metadata
Read a bounded samplePOST /v1/datasets/{dataset_id}/queryValidate integration behavior without downloading the complete artifact
Download the complete artifactGET /v1/datasets/{dataset_id}/releases/{release_id}/downloadStream JSONL, CSV, or Parquet after acceptance

Inspect first, then stream the accepted artifact

cURL
DATASET_ID="synthetic-finnish-vehicle-market"
RELEASE_ID="replace-with-accepted-release-id"

# Inspect the accepted release and its metadata first.
curl --fail --location \
  "https://api.datasets.nordicdevhouse.com/v1/datasets/$DATASET_ID/releases/$RELEASE_ID" \
  -H "Authorization: Bearer $DATASET_API_KEY" \
  -H "X-API-Version: 1"

# Download only after the release status and dataset label are accepted.
curl --fail --location \
  "https://api.datasets.nordicdevhouse.com/v1/datasets/$DATASET_ID/releases/$RELEASE_ID/download?format=parquet" \
  -H "Authorization: Bearer $DATASET_API_KEY" \
  -H "X-API-Version: 1" \
  --output "$RELEASE_ID.parquet"
Python
import os
from pathlib import Path
import requests

base_url = "https://api.datasets.nordicdevhouse.com/v1"
dataset_id = os.environ["DATASET_ID"]
release_id = os.environ["RELEASE_ID"]
headers = {
    "Authorization": f"Bearer {os.environ['DATASET_API_KEY']}",
    "X-API-Version": "1",
}

release = requests.get(
    f"{base_url}/datasets/{dataset_id}/releases/{release_id}",
    headers=headers,
    timeout=20,
)
release.raise_for_status()
manifest = release.json()
if manifest.get("quality_status") != "complete":
    raise RuntimeError("Release is not accepted for delivery")

target = Path(f"{release_id}.jsonl.part")
with requests.get(
    f"{base_url}/datasets/{dataset_id}/releases/{release_id}/download?format=jsonl",
    headers=headers,
    timeout=120,
    stream=True,
) as response:
    response.raise_for_status()
    with target.open("wb") as output:
        for chunk in response.iter_content(chunk_size=1024 * 1024):
            if chunk:
                output.write(chunk)

target.replace(target.with_suffix(""))
JavaScript
import { createWriteStream } from "node:fs";
import { pipeline } from "node:stream/promises";
import { Readable } from "node:stream";

const baseUrl = "https://api.datasets.nordicdevhouse.com/v1";
const { DATASET_API_KEY, DATASET_ID, RELEASE_ID } = process.env;
const headers = {
  Authorization: "Bearer " + DATASET_API_KEY,
  "X-API-Version": "1",
};

const releaseUrl = baseUrl + "/datasets/" + DATASET_ID + "/releases/" + RELEASE_ID;
const releaseResponse = await fetch(releaseUrl, { headers });
if (!releaseResponse.ok) throw new Error("Release lookup failed: " + releaseResponse.status);
const release = await releaseResponse.json();
if (release.quality_status !== "complete") throw new Error("Release is not accepted for delivery");

const download = await fetch(releaseUrl + "/download?format=jsonl", { headers });
if (!download.ok || !download.body) throw new Error("Download failed: " + download.status);
await pipeline(Readable.fromWeb(download.body), createWriteStream(RELEASE_ID + ".jsonl"));
  1. 1
    Copy the dataset and accepted release IDs from the dashboard or delivery handoff
  2. 2
    Fetch the release metadata and compare it with the approved dataset label
  3. 3
    Stop if quality or a required review is pending
  4. 4
    Stream the requested format into temporary storage
  5. 5
    Compute and store your own checksum with the release and label versions
  6. 6
    Promote the artifact atomically and retain lineage in downstream metadata

Limitations

Was this page helpful?