Skip to main content
POST
Create dataset

Authorizations

Authorization
string
header
required

API key with the vk_ prefix. Create one from the dashboard.

Body

JSON {name, format} for an empty stream, or a multipart JSONL file upload

JSON body for POST /v1/datasets: an empty stream with a locked format.

name
string
required
format
enum<string>
required

Row format every append is validated against.

Available options:
prompt,
preference,
completion,
chat
auto_snapshot_rows
integer<int32> | null

Optional rule: cut a snapshot automatically once this many rows have landed since the newest snapshot (evaluated by the reconciler).

Response

The created (or existing, on content-hash match) dataset

object
string
required
id
string
required
name
string
required
created_at
string<date-time>
required
source_type
string
source_uri
string | null
huggingface_dataset
string | null
num_rows
integer<int32> | null
format
string | null

Locked row format (prompt | preference | completion | chat). Null on a legacy dataset until its first append locks it.

head_row
integer<int64>

Highest row_id appended so far (0 = empty stream). Includes supersede and tombstone entries, so it is the log length, not the live row count.

auto_snapshot_rows
integer<int32> | null

"cut a snapshot every N new rows" rule; null = off.

latest_snapshot_id
string | null

Newest snapshot id ("@snap-N"); populated by GET /v1/datasets/{id}.

unsnapshotted_rows
integer<int64> | null

Rows appended since the newest snapshot; populated by GET /v1/datasets/{id}.

snapshot_count
integer<int64> | null