Workbench API

Projects, notebooks, events, dispatch, trust, and rewind endpoints.

Workbench API

The Workbench API provides access to the event-sourced MDM surface — projects, notebooks, tool dispatch, trust gates, and rewind/fork capabilities.

Scopes

List available scopes for project creation.

Response

[
  { "scope_type": "workspace", "scope_id": "ws_01", "name": "Default Workspace" },
  { "scope_type": "team", "scope_id": "team_01", "name": "Data Engineering" }
]

Projects

List all projects for the authenticated user.

Response

[
  {
    "id": "proj_01",
    "name": "Q1 Customer Dedup",
    "scope_type": "workspace",
    "scope_id": "ws_01",
    "default_trust": "gated",
    "active_notebook_id": "nb_01",
    "created_at": "2026-04-01T09:00:00Z"
  }
]

Create a new project.

Request

{
  "name": "Q1 Customer Dedup",
  "scope_type": "workspace",
  "scope_id": "ws_01",
  "default_trust": "gated"
}

Field	Type	Required	Description
`name`	string	Yes	Project display name
`scope_type`	string	Yes	`workspace`, `team`, or `org`
`scope_id`	string	Yes	ID of the scope
`default_trust`	string	No	Default trust level for new notebooks (`auto`, `gated`, `confirm`). Defaults to `gated`.

Response 201 Created

Returns the created project object.

Notebooks

List notebooks for a project.

Response

[
  {
    "id": "nb_01",
    "project_id": "proj_01",
    "name": "Initial run",
    "trust_level": "gated",
    "event_count": 42,
    "created_at": "2026-04-01T09:05:00Z"
  }
]

Create a new notebook within a project.

Request

{
  "project_id": "proj_01",
  "name": "Experiment A"
}

Response 201 Created

Returns the created notebook object.

Events

Retrieve the full event log for a notebook. Events are returned in sequence order.

Response

[
  {
    "seq": 1,
    "type": "tool_call",
    "tool_name": "goldencheck",
    "params": { "source_id": "src_01" },
    "result": { "issues_found": 12 },
    "created_at": "2026-04-01T09:10:00Z"
  }
]

Dispatch

Dispatch a tool call against the active notebook. The call is subject to the notebook's trust gate.

Request

{
  "tool_name": "goldenmatch",
  "params": {
    "source_id": "src_01",
    "threshold": 0.8
  }
}

Field	Type	Required	Description
`tool_name`	string	Yes	Registered MCP tool name
`params`	object	Yes	Tool-specific parameters

Response

{
  "seq": 43,
  "type": "tool_call",
  "tool_name": "goldenmatch",
  "gate_action": "auto",
  "result": { "scored_pairs": 120, "cluster_count": 34 }
}

Errors

Status	Meaning
`403 Forbidden`	Trust gate rejected the call (requires higher trust level)
`404 Not Found`	Notebook not found
`409 Conflict`	Notebook is not the active notebook for its project
`422 Unprocessable Entity`	Unknown tool name or invalid params

Trust

Update the trust level for a notebook.

Request

{
  "trust_level": "auto"
}

Field	Type	Required	Description
`trust_level`	string	Yes	One of `auto`, `gated`, or `confirm`

Response

{
  "id": "nb_01",
  "trust_level": "auto"
}

Rewind

Rewind a notebook to a previous event sequence number. All events after the target seq are soft-deleted.

Request

{
  "seq": 10
}

Field	Type	Required	Description
`seq`	integer	Yes	Sequence number to rewind to

Response

{
  "notebook_id": "nb_01",
  "rewound_to": 10,
  "events_removed": 32
}

Errors

Status	Meaning
`404 Not Found`	Notebook not found
`422 Unprocessable Entity`	Invalid sequence number

Fork

Fork a notebook at a given sequence number, creating a new notebook with events up to that point.

Request

{
  "at_seq": 10,
  "name": "Experiment B"
}

Field	Type	Required	Description
`at_seq`	integer	Yes	Sequence number to fork at
`name`	string	Yes	Name for the new notebook

Response 201 Created

{
  "id": "nb_02",
  "forked_from": "nb_01",
  "at_seq": 10,
  "name": "Experiment B"
}

Squash

Squash an event, collapsing it into the preceding event.

Response

{
  "notebook_id": "nb_01",
  "squashed_event_id": "evt_43",
  "new_event_count": 41
}

Errors

Status	Meaning
`404 Not Found`	Notebook or event not found
`409 Conflict`	Event cannot be squashed (e.g. first event)

← Entities Survivorship →