API-viite

Pyyntökentät, vastausobjektit ja tilakoodit.

12 min Päivitetty 2026-08-13Docs-versio 1.0

Tässä oppaassa

1Kanoninen OpenAPI-sopimus
2Päätepisteet
3Pyyntökentät
4Vastausobjektit

Tässä oppaassa

1Kanoninen OpenAPI-sopimus
2Päätepisteet
3Pyyntökentät
4Vastausobjektit

OpenAPI-sopimus

REST API 1.0.0:n kanoninen sopimus on OpenAPI 3.1.0 -dokumentti. API-viite, sopimustestit ja SDK-toteutukset käyttävät samaa lähdettä.

Avaa OpenAPI JSON

Päätepisteet

Metodi	Polku	Tarkoitus	Onnistuminen
POST	/v1/scrape	Create a scraping job	202
GET	/v1/jobs	List jobs	200
GET	/v1/jobs/{job_id}	Get a job	200
DELETE	/v1/jobs/{job_id}	Cancel a job	200
GET	/v1/jobs/{job_id}/stream	Stream completed job data	200
GET	/v1/events	List delivery events	200
GET	/v1/webhooks/deliveries	List webhook deliveries	200
GET	/v1/observability/metrics	Read API metrics	200
GET	/v1/datasets/{dataset_id}	Get a materialized dataset	200
POST	/v1/datasets/{dataset_id}/exports	Create a dataset export	202
GET	/v1/datasets/{dataset_id}/exports/{export_id}	Get a dataset export	200
GET	/v1/downloads/{export_id}	Download a completed dataset export	200

Scrape-pyynnön kentät

Kenttä	Tyyppi	Pakollinen
url	string	kyllä
formats	string[]	kyllä
webhook_url	string	ei
metadata	object	ei

Pyyntöesimerkit

cURL

curl -X POST https://api.nordicdevhouse.com/v1/scrape \\
  -H "Authorization: Bearer api_live_••••••••" \\n  -H "Content-Type: application/json" \\n  -H "Idempotency-Key: docs-example-001" \\
  -d '{
  "url": "https://example.com/products",
  "formats": [
    "json"
  ],
  "metadata": {
    "import_id": "catalog-2026-08-11"
  }
}'

TypeScript

const result = await ndh.request({
  method: 'POST',
  path: '/v1/scrape',
  body: { url: "https://example.com/products", formats: ["json"], metadata: { import_id: "catalog-2026-08-11" } }
});

Python

result = ndh.request(
    method="POST",
    path="/v1/scrape",
    body={
  "url": "https://example.com/products",
  "formats": [
    "json"
  ],
  "metadata": {
    "import_id": "catalog-2026-08-11"
  }
}
)

Työn vastausobjekti

Kenttä	Tyyppi	Pakollinen
id	string	kyllä
status	JobStatus	kyllä
created_at	string	kyllä
completed_at	string \| null	ei
retention_expires_at	string \| null	ei
request_id	string	kyllä
records	integer	ei
dataset_id	string \| null	ei
data	object	ei
warnings	array	ei
last_event_id	string \| null	ei
metadata	object	ei

Create a scraping job – yksityiskohdat

POST /v1/scrapeSandbox

Create a scraping job

Creates one idempotent scraping job. The response is asynchronous; use the returned job ID or a verified webhook to observe completion.

Vastaukset

202 Job accepted

""

400

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 400",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

401

{
  "error": {
    "code": "unauthorized",
    "message": "Request failed with HTTP 401",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

429

{
  "error": {
    "code": "rate_limited",
    "message": "Request failed with HTTP 429",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

500

{
  "error": {
    "code": "server_error",
    "message": "Request failed with HTTP 500",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

cURL

curl -X POST https://api.nordicdevhouse.com/v1/scrape \\
  -H "Authorization: Bearer api_live_••••••••" \\n  -H "Content-Type: application/json" \\n  -H "Idempotency-Key: docs-example-001" \\
  -d '{
  "url": "https://example.com/products",
  "formats": [
    "json"
  ],
  "metadata": {
    "import_id": "catalog-2026-08-11"
  }
}'

TypeScript

const result = await ndh.request({
  method: 'POST',
  path: '/v1/scrape',
  body: { url: "https://example.com/products", formats: ["json"], metadata: { import_id: "catalog-2026-08-11" } }
});

Python

result = ndh.request(
    method="POST",
    path="/v1/scrape",
    body={
  "url": "https://example.com/products",
  "formats": [
    "json"
  ],
  "metadata": {
    "import_id": "catalog-2026-08-11"
  }
}
)

List jobs – yksityiskohdat

GET /v1/jobsSandbox

List jobs

Returns jobs in reverse creation order with cursor pagination.

Vastaukset

200 Job page

""

400

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 400",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

401

{
  "error": {
    "code": "unauthorized",
    "message": "Request failed with HTTP 401",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

429

{
  "error": {
    "code": "rate_limited",
    "message": "Request failed with HTTP 429",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

500

{
  "error": {
    "code": "server_error",
    "message": "Request failed with HTTP 500",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

Get a job – yksityiskohdat

GET /v1/jobs/{job_id}Sandbox

Get a job

Returns the current state and, when completed, the validated result.

Vastaukset

200 Current job

""

400

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 400",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

401

{
  "error": {
    "code": "unauthorized",
    "message": "Request failed with HTTP 401",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

404

{
  "error": {
    "code": "not_found",
    "message": "Request failed with HTTP 404",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

429

{
  "error": {
    "code": "rate_limited",
    "message": "Request failed with HTTP 429",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

500

{
  "error": {
    "code": "server_error",
    "message": "Request failed with HTTP 500",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

Cancel a job – yksityiskohdat

DELETE /v1/jobs/{job_id}Sandbox

Cancel a job

Cancels queued or running work. Completed, failed, and already canceled jobs are returned unchanged.

Vastaukset

200 Canceled or already terminal job

""

400

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 400",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

401

{
  "error": {
    "code": "unauthorized",
    "message": "Request failed with HTTP 401",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

404

{
  "error": {
    "code": "not_found",
    "message": "Request failed with HTTP 404",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

409

{
  "error": {
    "code": "conflict",
    "message": "Request failed with HTTP 409",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

429

{
  "error": {
    "code": "rate_limited",
    "message": "Request failed with HTTP 429",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

500

{
  "error": {
    "code": "server_error",
    "message": "Request failed with HTTP 500",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

Stream completed job data – yksityiskohdat

GET /v1/jobs/{job_id}/streamSandbox

Stream completed job data

Returns one JSON record per line using application/x-ndjson after the job has completed.

Vastaukset

200 NDJSON result stream

""

400

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 400",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

401

{
  "error": {
    "code": "unauthorized",
    "message": "Request failed with HTTP 401",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

404

{
  "error": {
    "code": "not_found",
    "message": "Request failed with HTTP 404",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

409

{
  "error": {
    "code": "conflict",
    "message": "Request failed with HTTP 409",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

410

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 410",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

413

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 413",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

429

{
  "error": {
    "code": "rate_limited",
    "message": "Request failed with HTTP 429",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

500

{
  "error": {
    "code": "server_error",
    "message": "Request failed with HTTP 500",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

List delivery events – yksityiskohdat

GET /v1/eventsSandbox

List delivery events

Returns signed webhook-worthy events in cursor-paginated order.

Vastaukset

200 Event page

""

400

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 400",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

401

{
  "error": {
    "code": "unauthorized",
    "message": "Request failed with HTTP 401",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

429

{
  "error": {
    "code": "rate_limited",
    "message": "Request failed with HTTP 429",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

500

{
  "error": {
    "code": "server_error",
    "message": "Request failed with HTTP 500",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

List webhook deliveries – yksityiskohdat

GET /v1/webhooks/deliveriesSandbox

List webhook deliveries

Returns delivery attempts and dead-letter state for local or test webhook endpoints.

Vastaukset

200 Webhook delivery list

{
  "data": []
}

400

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 400",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

401

{
  "error": {
    "code": "unauthorized",
    "message": "Request failed with HTTP 401",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

429

{
  "error": {
    "code": "rate_limited",
    "message": "Request failed with HTTP 429",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

500

{
  "error": {
    "code": "server_error",
    "message": "Request failed with HTTP 500",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

Read API metrics – yksityiskohdat

GET /v1/observability/metricsSandbox

Read API metrics

Returns in-process request counters and durations for the fake API runtime.

Vastaukset

200 Metrics snapshot

""

400

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 400",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

401

{
  "error": {
    "code": "unauthorized",
    "message": "Request failed with HTTP 401",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

429

{
  "error": {
    "code": "rate_limited",
    "message": "Request failed with HTTP 429",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

500

{
  "error": {
    "code": "server_error",
    "message": "Request failed with HTTP 500",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

Get a materialized dataset – yksityiskohdat

GET /v1/datasets/{dataset_id}Sandbox

Get a materialized dataset

Returns the immutable dataset created by a completed scrape job.

Vastaukset

200 Materialized dataset

""

400

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 400",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

401

{
  "error": {
    "code": "unauthorized",
    "message": "Request failed with HTTP 401",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

404

{
  "error": {
    "code": "not_found",
    "message": "Request failed with HTTP 404",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

429

{
  "error": {
    "code": "rate_limited",
    "message": "Request failed with HTTP 429",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

500

{
  "error": {
    "code": "server_error",
    "message": "Request failed with HTTP 500",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

Create a dataset export – yksityiskohdat

POST /v1/datasets/{dataset_id}/exportsSandbox

Create a dataset export

Creates an immutable export from a dataset version.

Vastaukset

202 Export accepted

""

400

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 400",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

401

{
  "error": {
    "code": "unauthorized",
    "message": "Request failed with HTTP 401",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

404

{
  "error": {
    "code": "not_found",
    "message": "Request failed with HTTP 404",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

429

{
  "error": {
    "code": "rate_limited",
    "message": "Request failed with HTTP 429",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

500

{
  "error": {
    "code": "server_error",
    "message": "Request failed with HTTP 500",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

cURL

curl -X POST https://api.nordicdevhouse.com/v1/datasets/{dataset_id}/exports \\
  -H "Authorization: Bearer api_live_••••••••" \\n  -H "Content-Type: application/json" \\n  -H "Idempotency-Key: docs-example-001" \\
  -d '{
  "format": "json",
  "mode": "snapshot"
}'

TypeScript

const result = await ndh.request({
  method: 'POST',
  path: '/v1/datasets/{dataset_id}/exports',
  body: { format: "json", mode: "snapshot" }
});

Python

result = ndh.request(
    method="POST",
    path="/v1/datasets/{dataset_id}/exports",
    body={
  "format": "json",
  "mode": "snapshot"
}
)

Get a dataset export – yksityiskohdat

GET /v1/datasets/{dataset_id}/exports/{export_id}Sandbox

Get a dataset export

Returns export state and a short-lived download URL when ready.

Vastaukset

200 Current export

""

400

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 400",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

401

{
  "error": {
    "code": "unauthorized",
    "message": "Request failed with HTTP 401",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

404

{
  "error": {
    "code": "not_found",
    "message": "Request failed with HTTP 404",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

429

{
  "error": {
    "code": "rate_limited",
    "message": "Request failed with HTTP 429",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

500

{
  "error": {
    "code": "server_error",
    "message": "Request failed with HTTP 500",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

Download a completed dataset export – yksityiskohdat

GET /v1/downloads/{export_id}Sandbox

Download a completed dataset export

Streams the completed export as JSON, CSV, or opaque Parquet bytes. Download URLs expire independently from export metadata.

Vastaukset

200 Export bytes

[]

400

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 400",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

401

{
  "error": {
    "code": "unauthorized",
    "message": "Request failed with HTTP 401",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

404

{
  "error": {
    "code": "not_found",
    "message": "Request failed with HTTP 404",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

409

{
  "error": {
    "code": "conflict",
    "message": "Request failed with HTTP 409",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

410

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 410",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

413

{
  "error": {
    "code": "request_failed",
    "message": "Request failed with HTTP 413",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

429

{
  "error": {
    "code": "rate_limited",
    "message": "Request failed with HTTP 429",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

500

{
  "error": {
    "code": "server_error",
    "message": "Request failed with HTTP 500",
    "request_id": "req_example"
  }
}

Generoitu status-sopimuksesta

Oliko tästä sivusta apua?

Muutosloki Pika-aloitus Scraping API