All pages
API events
Every v2 event the API accepts, with example data. Send organization events to /api/v2/events, experiment events with an experiment token to /api/v2/experiments/{experimentId}/events, and series queries to /api/v2/query/series. The envelope, batching and error rules are on HTTP API; the complete JSON schemas are in the OpenAPI document at /api/openapi.json.
syvain.v2.folder.create
Creates a folder. parentFolderId: null places it at the root. Replies with syvain.v2.folder.created containing folderId, name, and parentFolderId.
{
"messageId": "3f0c…",
"event": "syvain.v2.folder.create",
"data": {
"name": "Research",
"parentFolderId": null
}
}syvain.v2.folder.move
Moves a folder from its expected parent to toFolderId. null means the root. A stale fromFolderId conflicts; cycles are rejected. Replies with syvain.v2.folder.moved and the same data fields.
{
"messageId": "3f0c…",
"event": "syvain.v2.folder.move",
"data": {
"folderId": "folder-id",
"fromFolderId": null,
"toFolderId": "parent-id"
}
}syvain.v2.folder.rename
Renames a folder in place. The name must be nonblank, contain no slash, and be unique among its siblings; a duplicate fails with folder_already_exists. Replies with syvain.v2.folder.renamed and the same data fields.
{
"messageId": "3f0c…",
"event": "syvain.v2.folder.rename",
"data": {
"folderId": "folder-id",
"name": "Research 2026"
}
}syvain.v2.folderexperiment.move
Moves an experiment from its expected folder. null means the root. A stale fromFolderId conflicts. Replies with syvain.v2.folderexperiment.moved and the same data fields.
{
"messageId": "3f0c…",
"event": "syvain.v2.folderexperiment.move",
"data": {
"experimentId": "experiment-id",
"fromFolderId": null,
"toFolderId": "folder-id"
}
}syvain.v2.foldertree.read
Reads the complete organization folder tree. Reply event is also syvain.v2.foldertree.read. data.folders is recursive; data.experiments contains root experiments. Each experiment entry contains experimentId and slug. Set the optional includeDisplayNames: true to also receive displayName, a string or null, on every experiment entry; without it the field is absent.
{
"messageId": "3f0c…",
"event": "syvain.v2.foldertree.read",
"data": {}
}syvain.v2.experiment.open
Creates or reopens the organization experiment identified by slug. On reopen, replaces description and meta without resetting lifecycle status. Omitted description becomes an empty string. Replies with syvain.v2.experiment.opened containing experimentId, experimentToken, and expiresAtMs. Each call issues a new token.
{
"messageId": "3f0c…",
"event": "syvain.v2.experiment.open",
"data": {
"slug": "agent-run-001",
"description": "Agent experiment",
"meta": {}
}
}syvain.v2.experiment.rename
Sets the display name of a visible experiment; the slug is unchanged. The name is trimmed and must be nonblank and at most 200 characters; null clears it. An unknown experiment fails with experiment_not_found. Replies with syvain.v2.experiment.renamed and the same data fields.
{
"messageId": "3f0c…",
"event": "syvain.v2.experiment.rename",
"data": {
"experimentId": "experiment-id",
"displayName": "Baseline, lr 3e-4"
}
}syvain.v2.view.save
Creates or updates an organization saved view. viewId: null creates one with a server-generated viewId; otherwise the view is replaced, and an unknown viewId fails with view_not_found. The name is trimmed, nonblank, at most 200 characters, and unique in the organization; a duplicate fails with view_already_exists and details.viewId of the existing view. state is an opaque JSON object of at most 65536 bytes of compact JSON. Replies with syvain.v2.view.saved containing viewId, name, and updatedAtMs.
{
"messageId": "3f0c…",
"event": "syvain.v2.view.save",
"data": {
"viewId": null,
"name": "Loss curves",
"state": {
"version": 1
}
}
}syvain.v2.view.delete
Deletes an organization saved view. An unknown viewId fails with view_not_found. Replies with syvain.v2.view.deleted and the same data fields.
{
"messageId": "3f0c…",
"event": "syvain.v2.view.delete",
"data": {
"viewId": "view-id"
}
}syvain.v2.query.views
Lists the organization's saved views sorted by name. Replies with syvain.v2.query.views.result containing views with viewId, name, state, createdAtMs, and updatedAtMs.
{
"messageId": "3f0c…",
"event": "syvain.v2.query.views",
"data": {}
}syvain.v2.experiment.tokenRefresh
Requires the organization key as bearer credential and the current experiment token in data. Replies with syvain.v2.experiment.tokenRefreshed containing experimentId, the new experimentToken, and expiresAtMs. An expired or revoked token cannot be refreshed.
{
"messageId": "3f0c…",
"event": "syvain.v2.experiment.tokenRefresh",
"data": {
"experimentId": "experiment-id",
"experimentToken": "current-token"
}
}syvain.v2.query.experiment
Accepts exactly one identity field. Replies with syvain.v2.query.experiment.result containing experiment, including slug, description, meta, status, error, and lifecycle timestamps in Unix milliseconds. Unset timestamps and error are null.
{
"messageId": "3f0c…",
"event": "syvain.v2.query.experiment",
"data": {
"experimentSlug": "agent-run-001"
}
}syvain.v2.query.experiments
Reads up to 500 experimentIds with bounded parallel reads. This must be the only event in the request. Replies with syvain.v2.query.experiments.result containing experiments and missingExperimentIds. Records include the same fields as query.experiment, plus experimentRevision and seriesRevision. Duplicate IDs are collapsed. Unknown and inaccessible IDs appear in missingExperimentIds.
{
"messageId": "3f0c…",
"event": "syvain.v2.query.experiments",
"data": {
"experimentIds": [
"experiment-id"
]
}
}syvain.v2.query.revisions
Checks up to 500 experimentIds with bounded parallel reads. This must be the only event in the request. Replies with query.revisions.result containing revisions and missingExperimentIds. Duplicate IDs are collapsed. experimentRevision changes with record updates and annotations; seriesRevision changes with committed metric activity. Activity updates are best effort after series ingestion, so revisions are cache hints, not transactional snapshots. Compare each counter for equality; metadata and series have separate cache lifetimes.
{
"messageId": "3f0c…",
"event": "syvain.v2.query.revisions",
"data": {
"experimentIds": [
"experiment-id"
]
}
}syvain.v2.query.catalog
Accepts exactly one identity field. Replies with syvain.v2.query.catalog.result containing experimentId and series. Each series contains seriesName and metadata entries with key and values.
{
"messageId": "3f0c…",
"event": "syvain.v2.query.catalog",
"data": {
"experimentId": "experiment-id"
}
}syvain.v2.query.annotations
Accepts exactly one identity field. Replies with syvain.v2.query.annotations.result containing experimentId and annotations with annotationId, annotation, meta, and createdAtMs.
{
"messageId": "3f0c…",
"event": "syvain.v2.query.annotations",
"data": {
"experimentId": "experiment-id"
}
}syvain.v2.query.series
Uses the dedicated /api/v2/query/series endpoint with an organization key. Requires exactly one identity field, seriesName, filter, and xAxis. Returns syvain.v2.query.series.data records followed by syvain.v2.query.series.done, or syvain.v2.error. See stream completion rules above.
{
"messageId": "3f0c…",
"event": "syvain.v2.query.series",
"data": {
"experimentId": "experiment-id",
"seriesName": "loss",
"filter": [],
"xAxis": "step"
}
}syvain.v2.query.experimentseries
Uses the dedicated /api/v2/query/series endpoint with an organization key. Requires exactly one identity field, filter, and xAxis; seriesNames is optional. Returns interleaved syvain.v2.query.series.data records, one syvain.v2.query.experimentseries.series record per series after its data, then syvain.v2.query.experimentseries.done, or syvain.v2.error.
{
"messageId": "3f0c…",
"event": "syvain.v2.query.experimentseries",
"data": {
"experimentId": "experiment-id",
"seriesNames": [
"loss",
"accuracy"
],
"filter": [],
"xAxis": "step"
}
}syvain.v2.experiment.start
Sets status to running using server time. Preserves the first startedAtMs, clears a previous error and doneAtMs, and updates activity. Replies with syvain.v2.experiment.started containing experimentId.
{
"messageId": "3f0c…",
"event": "syvain.v2.experiment.start",
"data": {
"experimentId": "experiment-id"
}
}syvain.v2.experiment.done
Sets status to done and doneAtMs to server time, and clears a previous error. Replies with syvain.v2.experiment.done containing experimentId. Does not revoke the token.
{
"messageId": "3f0c…",
"event": "syvain.v2.experiment.done",
"data": {
"experimentId": "experiment-id"
}
}syvain.v2.experiment.error
Sets status to error and doneAtMs to server time. error is a nonempty message of at most 8000 characters; meta is a JSON object. Replies with syvain.v2.experiment.errored containing experimentId.
{
"messageId": "3f0c…",
"event": "syvain.v2.experiment.error",
"data": {
"experimentId": "experiment-id",
"error": "Training failed",
"meta": {}
}
}syvain.v2.experiment.annotate
Creates an annotation with JSON metadata and a server timestamp. Replies with syvain.v2.experiment.annotated containing experimentId and annotationId. Repeating the request can create another annotation.
{
"messageId": "3f0c…",
"event": "syvain.v2.experiment.annotate",
"data": {
"experimentId": "experiment-id",
"annotation": "Evaluation completed",
"meta": {}
}
}syvain.v2.experiment.metric
Records one finite metricValue. timestampMs is Unix milliseconds from 0 to 9007199254740991; step is an integer from 0 to 9007199254740990. meta maps strings to strings and distinguishes series. It allows at most 32 keys, 128 UTF-8 bytes per key, 512 bytes per value, and 4096 bytes of canonical JSON. Replies with syvain.v2.experiment.metricRecorded containing experimentId and accepted: true after ingestion completes. Preserve messageId and the entire payload on retry.
{
"messageId": "3f0c…",
"event": "syvain.v2.experiment.metric",
"data": {
"experimentId": "experiment-id",
"timestampMs": 1789776000000,
"step": 1,
"metricName": "loss",
"metricValue": 0.25,
"meta": {
"split": "train"
}
}
}syvain.v2.experiment.tokenRevoke
Revokes the bearer experiment token used for this request. Must be the final event in a batch. Replies with syvain.v2.experiment.tokenRevoked containing experimentId. Later requests with this token fail authentication.
{
"messageId": "3f0c…",
"event": "syvain.v2.experiment.tokenRevoke",
"data": {
"experimentId": "experiment-id"
}
}