Service twin · API only

Unstructured

Test document-processing agents that partition files and run ingestion workflows.

API onlydocs-transcribedREST · MCP · CLI

Start a twin run Read the quickstart Open the live explorer

Terminal

$ uv tool install --with "blobfish-sdk @ https://blobfish.ai/sdk/blobfish_sdk-0.6.2-py3-none-any.whl" "blobfish-cli @ https://blobfish.ai/sdk/blobfish_cli-0.1.13-py3-none-any.whl"
$ blobfish login
$ blobfish twin-runs create --twins unstructured --ttl 60 --wait

What’s inside

A deterministic, seeded, resettable replica: every operation below executes real state transitions against the twin’s own SQLite state — reads are hash-invariant, writes produce inspectable diffs, and reset restores the seed baseline.

Operations26

Writes14

Entities6

Lifecycles2

Seeded entities

Entity	Table	Fields	About
source_connector	`source_connectors`	6	Source connector that a workflow ingests raw files from.
destination_connector	`destination_connectors`	6	Destination connector that processed elements are written to.
workflow	`workflows`	7	Ingestion workflow wiring a source to a destination on a schedule.
job	`jobs`	7	One execution of a workflow, moving through a run lifecycle.
document	`documents`	7	A file processed by a job, from which partition elements were extracted.
partition_element	`partition_elements`	6	One structured element produced by partitioning a document.

Guarded lifecycles

These state machines are enforced, not decorative: an action whose from state doesn’t match is rejected the way the production service rejects it.

workflow.status

active → paused

pause: active → paused
resume: paused → active

job.status

scheduled → in_progress → completed → failed → cancelled

run: scheduled → in_progress
cancel: scheduled|in_progress → cancelled

Three surfaces, one state

Mount Unstructured in a twin environment and the same seeded state serves vendor-shaped REST operations, an MCP endpoint for tool calling, and a generated bf-twin CLI — with copy-on-write sessions per rollout and a one-call reset to the seed baseline. Prefer raw HTTP? The same create works with curl:

API

$ curl -sS -X POST https://blobfish.ai/api/v1/twin/environments \
    -H "X-API-Key: $BLOBFISH_API_KEY" -H "Content-Type: application/json" \
    -d '{"services":["unstructured"],"ttl_minutes":60}'

Known limitations

transcribed from https://docs.unstructured.io/api-reference/workflow/overview; parameter and response schemas simplified
synthetic seeded values
processed documents and partition elements exposed as flat read collections
job run modeled as an explicit per-job lifecycle action