Datasets

POST/v1/orgs/{org_id}/datasets

Create Dataset

Create a new evaluation dataset.

CI or Admin tokenscope: writeoperation_id: datasets.create

Authentication

Requires a CI- or admin-level token. Runtime tokens are rejected for mutations.

SDK install

pip install znyx-sdknpm install @znyx/sdk

Path parameters

Name	Type	Required	Description
org_id#path	string	required	—

Header parameters

Name	Type	Required	Description
X-API-Key#header	string \| null	optional	—
authorization#header	string \| null	optional	—

Request bodyrequired

Field	Type	Required	Description
name	string	required	—
description	string \| null	optional	—
category	string \| null	optional	—
trust_level	string	optional	—
is_public	boolean	optional	—
created_by	string \| null	optional	—

Responses

Status	Description
200	Successful Response
422	Validation Error

Response schema

idrequiredstring

namerequiredstring

descriptionstring | null

categorystring | null

trust_levelstring

sourcestring

sample_countinteger

is_publicboolean

created_bystring | null

created_atstring | null

updated_atstring | null

Errors & what triggers them

Code	Trigger	Fix
401	Missing or expired Authorization header.	—
403	Token does not have the required role (admin / editor).	—
404	Target resource does not exist in this org.	—
422	Request body failed validation.	—

Notes & examples

The minimum body

{
  "name": "support-bot-fp-regression"
}

Name is the only required field. description, category, trust_level, is_public, and created_by are all optional metadata and you can edit them later from the Datasets page.

Two ways to populate

Programmatic batch — POST /v1/orgs/{org_id}/datasets/{id}/samples with a list of {input_text, context, expected_decision, expected_rule_hits, metadata} objects. Up to a few thousand per call is fine.
File import — POST /v1/orgs/{org_id}/datasets/{id}/import with raw JSON / CSV content in the body. Good for bulk-loading existing eval sets.

Prefer `source=customer`

Custom datasets default to source=customer which keeps them out of the "browse catalog" view. Use this for private regression sets. If you're maintaining an open benchmark, flip is_public=true.

GET /v1/orgs/{org_id}/datasets/catalog — browse bundled ZNYX + industry-standard benchmarks before rolling your own.
POST /v1/orgs/{org_id}/annotations/export — turn annotated traces into a fresh dataset in one call.

Request

curl -X POST 'https://api.znyx.ai/v1/orgs/00000000-0000-0000-0000-000000000000/datasets' \
  -H 'Authorization: Bearer $ZNYX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": null,
  "category": null,
  "trust_level": "custom",
  "is_public": false,
  "created_by": null
}'

Response

application/json

Successful Response

{
  "id": "string",
  "name": "string",
  "description": null,
  "category": null,
  "trust_level": "string",
  "source": "string",
  "sample_count": 0,
  "is_public": false,
  "created_by": null,
  "created_at": null,
  "updated_at": null
}

Schema: object