Research

Package research is every experiment you have ever run, kept and comparable.

All API references → · Six flows, four surfaces →


Base URL	`https://api.hanzo.ai`
Operations	8
Auth	`Authorization: Bearer $HANZO_API_KEY`

Retrieve an artifact's bytes by content hash (org-scoped)

GET /v1/research/artifacts/{sha256}

Parameter	In	Type	Required	Description
`sha256`	path	string	yes	The artifact content hash.
`project`	query	string	—

ListResearchArtifacts returns the caller org's research-diary feed newest-first — the snapshots and reports tied to its runs, as metadata and content addresses; the bytes themselves are fetched by hash.

GET /v1/research/artifacts

ListResearchArtifacts returns the caller org's research-diary feed newest-first — the snapshots and reports tied to its runs, as metadata and content addresses; the bytes themselves are fetched by hash. ?run= narrows to one run, ?project= to one project (default the caller's project scope), and ?since= to a unix second.

Parameter	In	Type	Required	Description
`project`	query	string	—	Project narrows to one project.
`run`	query	string	—	Run narrows to one run's artifacts by its stable id.
`since`	query	integer	—	Since bounds the feed to artifacts recorded at or after this unix second.

RecordResearchArtifact records one research-diary artifact — a board snapshot or a generated report — CONTENT-ADDRESSED inside the trust boundary.

POST /v1/research/artifacts

RecordResearchArtifact records one research-diary artifact — a board snapshot or a generated report — CONTENT-ADDRESSED inside the trust boundary. The caller submits the bytes as base64 content; the SERVER hashes them and THAT hash is the identity and the ref, so the address can never be poisoned by a client-asserted one. A client-supplied sha256, if present, must match the bytes. The project is the SERVER's value and visibility is forced private. Re-posting the same bytes is a no-op that reports created=false.

Request body — application/json (required)

Field	Type	Required	Description
`content`	string	—	base64 bytes on write; the server hashes + stores them (never returned)
`git_branch`	string	—
`git_dirty`	boolean	—
`git_sha`	string	—
`kind`	string	—
`lib_versions`		—
`project`	string	—
`ref`	string	—	server-derived content address (sha256:<hash>)
`retention_class`	string	—
`run_id`	string	—
`sha256`	string	—	SERVER-derived on write; the identity
`ts`	integer	—
`visibility`	string	—

ListExperiments returns the caller org's CANONICAL experiments — the deterministic deduped view over the versioned history.

GET /v1/research/experiments

ListExperiments returns the caller org's CANONICAL experiments — the deterministic deduped view over the versioned history. With no ?project= it reads the org's whole set across projects (the ops board's cross-project view, since a project is a sub-scope of the one tenant); ?project= narrows to one and ?kind= to one discriminator.

Parameter	In	Type	Required	Description
`project`	query	string	—	Project narrows to one project.
`kind`	query	string	—	Kind narrows to one discriminator: benchmark, kernel-perf, training, ablation or policy-eval.

IngestExperiments appends one batch of experiment and attempt versions to the caller org's evidence store, idempotently by content, then rolls it up to the analytics plane best-effort.

POST /v1/research/experiments

IngestExperiments appends one batch of experiment and attempt versions to the caller org's evidence store, idempotently by content, then rolls it up to the analytics plane best-effort. The project is the SERVER's value and visibility is forced private — an upload grants no training or publication right, which is a separate call. A run carrying a BYO endpoint is SSRF-checked before the store is touched. The answer carries BOTH the canonical (deduped) and retained (full history) counts, so a caller sees the versioned truth rather than a dedup that reads as loss.

Request body — application/json (required)

Field	Type	Required	Description
`attempts`	cloud_Attempt[]	—
`experiments`	cloud_Experiment[]	—

POST /v1/research/grants

GrantResearchVisibility records the SEPARATE authorization an upload never implies: a record's visibility (private, org or public) and, for a run, its training and commons-publication consent. Address a run by its stable id or an artifact by its sha256; an artifact grant sets visibility only. The ORG is the tenant boundary and comes from the validated principal, so a caller can only ever grant within its own org; project locates WHICH record inside it and defaults to the caller's project scope.

Request body — application/json (required)

Field	Type	Required	Description
`id`	string	—	an experiment (run) stable id
`project`	string	—
`publishable`	boolean	—
`sha256`	string	—	OR an artifact content hash
`trainable`	boolean	—
`visibility`	string	—

ListResearchProjects returns every research project in the caller's org with its real totals — canonical and retained side by side — which is the ops board's "every project + real totals" view.

GET /v1/research/projects

ListResearchProjects returns every research project in the caller's org with its real totals — canonical and retained side by side — which is the ops board's "every project + real totals" view.

GetResearchTotals returns the caller org's headline aggregate plus a per-kind breakdown — the observatory's poll target.

GET /v1/research/totals

GetResearchTotals returns the caller org's headline aggregate plus a per-kind breakdown — the observatory's poll target. Canonical and retained counts travel together, so a deduped view never reads as loss. ?project= narrows to one project.

Parameter	In	Type	Required	Description
`project`	query	string	—	Project narrows the aggregate to one project.

All Hanzo APIs · Interactive reference

Research

On this page