Declare the next version of a dataset

Declares the next version of a dataset from a bound query over this org's own feature surface.

POST /v1/dataset

Dataset → · All API references → · Six flows, four surfaces →


Address	`https://api.hanzo.ai/v1/dataset`
Method	`POST`
Operation	`riskCreateDataset`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Declares the next version of a dataset from a bound query over this org's own feature surface.

It mints a VERSION and writes no rows: a version is declared, then materialised once, then never rewritten. Version numbers are monotone and never reused, so "version 3 of signups" means one thing forever — which is the whole reason a model can cite one.

The window is bounded by the source's retention, the horizon by a year, the rows by the plane's cap, and the number of datasets and versions per org by their own limits. Every refusal names which bound it hit.

Request

9 fields, body application/json (required).

Field	In	Type	Required	Description
`cuts`	body	string[]	—	Cuts are the two RFC 3339 instants dividing train \| val \| test. Omit them to take 70% and 85% of the window by time.
`dims`	body	string[]	—	Dims are the coordinates to carry, by published name. Empty takes the whole surface.
`from`	body	string	—	From is where the event window opens, RFC 3339, INCLUSIVE.
`horizon`	body	integer	—	Horizon is how many days a row must have aged before it may be admitted.
`kind`	body	string	—	Kind narrows to one subject kind — person, session or account.
`name`	body	string	—	Name identifies the dataset across its versions: lower-case letters, digits and hyphens, starting with a letter.
`rows`	body	integer	—	Rows caps the materialisation.
`seed`	body	string	—	Seed decides WHICH subjects are admitted when the window holds more rows than the cap allows.
`to`	body	string	—	To is where the window ends, EXCLUSIVE, so two datasets meeting at one instant share no row.

Response

Status	Body	Meaning
`200`	riskDataset	ok

200 body — 30 fields.

Field	In	Type	Always	Description
`at`	body	string	—	At is when this version last changed state, RFC 3339 UTC.
`by`	body	string	—	By is who moved it there: the validated user, or the org itself when the caller is a machine with no user behind it.
`counts`	body	riskSplitCounts	—
`counts.judged`	body	integer	—	Judged is how many rows carry a disposition.
`counts.productive`	body	integer	—	Productive is how many judged rows carry the one disposition.
`counts.rows`	body	integer	—	Rows is how many rows the version holds across every split.
`counts.subjects`	body	integer	—	Subjects is how many distinct subjects the rows belong to.
`counts.test`	body	integer	—	Test is how many fall after the second cut — the LATEST slice, and the only one a score is honest about, since the split is temporal.
`counts.train`	body	integer	—	Train is how many rows fall before the first cut — the EARLIEST slice of the window, which is what a model is fitted on.
`counts.unproductive`	body	integer	—	Unproductive is how many carry the other. With Productive it accounts for Judged, so the class imbalance is visible before anyone trains on it; both stay 0…
`counts.val`	body	integer	—	Val is how many fall between the two cuts, held out for tuning.
`digest`	body	string	—	Digest fingerprints the SPEC and the ROWS together.
`name`	body	string	—	Name identifies the dataset across all of its versions.
`oversize`	body	integer	—	Oversize is how many of the window's subjects this version could NOT carry because their subject identity exceeds the plane's per-subject byte bound.
`refusal`	body	string	—	Refusal names why there are no bytes, when there are none.
`running`	body	boolean	—	Running is true while THIS process is materialising the version.
`share`	body	integer	—	Share is the fraction of the window's subjects admitted, in thousandths.
`spec`	body	riskDatasetSpec	—
`spec.cuts`	body	string[]	—	Cuts are the two RFC 3339 instants dividing train \| val \| test. Omit them to take 70% and 85% of the window by time.
`spec.dims`	body	string[]	—	Dims are the coordinates to carry, by published name. Empty takes the whole surface.
`spec.from`	body	string	—	From is where the event window opens, RFC 3339, INCLUSIVE.
`spec.horizon`	body	integer	—	Horizon is how many days a row must have aged before it may be admitted.
`spec.kind`	body	string	—	Kind narrows to one subject kind — person, session or account.
`spec.name`	body	string	—	Name identifies the dataset across its versions: lower-case letters, digits and hyphens, starting with a letter.
`spec.rows`	body	integer	—	Rows caps the materialisation.
`spec.seed`	body	string	—	Seed decides WHICH subjects are admitted when the window holds more rows than the cap allows.
`spec.to`	body	string	—	To is where the window ends, EXCLUSIVE, so two datasets meeting at one instant share no row.
`status`	body	string	—	Status is declared, materializing, ready or refused.
`truncated`	body	boolean	—	Truncated is true when the row cap bound before the window ran out.
`version`	body	integer	—	Version is which version this is, from 1 and monotone within the dataset.

Failure carries the platform error shape — see Errors.

Examples

hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.

import { Configuration, DatasetApi } from 'hanzoai';

const api = new DatasetApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.riskCreateDataset({ cuts: ["<cuts>"], dims: ["<dims>"] });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import DatasetApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = DatasetApi(client).risk_create_dataset(cuts=["<cuts>"], dims=["<dims>"])

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.DatasetAPI.RiskCreateDataset(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, dataset_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = dataset_api::risk_create_dataset(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.DatasetApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new DatasetApi(client).riskCreateDataset();

curl -X POST https://api.hanzo.ai/v1/dataset \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "cuts": [
         "<cuts>"
       ],
       "dims": [
         "<dims>"
       ]
     }'

Tool dataset, op riskCreateDataset — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "dataset",
         "arguments": {
           "op": "riskCreateDataset",
           "input": {
             "cuts": [
               "<cuts>"
             ],
             "dims": [
               "<dims>"
             ]
           }
         }
       }
     }'

Dataset API · All Hanzo APIs · Interactive reference

Declare the next version of a dataset

Request

Response

Examples

On this page