Tapicker Bridge API Reference
This page is a quick index. For setup steps, see Getting Started. For AI integrations, see Connect an AI Agent.
CLI Commands
| Command | Purpose |
|---|---|
tapicker bridge start [--daemon] | Start Bridge in the foreground or in the background |
tapicker bridge stop | Stop a background Bridge |
tapicker bridge code [--refresh] | Show or rotate the Extension pairing code |
tapicker bridge extensions | List connected Extension clients |
tapicker workflow start <workflowId> [--watch] | Start a Workflow and optionally stream its status |
tapicker workflow pause <workflowId> | Pause a Workflow |
tapicker workflow resume <workflowId> | Resume a paused Workflow |
tapicker workflow stop <workflowId> | Stop a Workflow |
tapicker workflow status <workflowId> | Get the latest Workflow status snapshot |
tapicker workflow status <workflowId> --watch | Wait for Workflow status updates |
tapicker workflow logs <workflowId> | Query latest-run log previews |
tapicker workflow log <workflowId> <logId> | Read a log with full details |
tapicker data get <tableId> | Read an extracted data table |
tapicker data delete <tableId> | Delete an extracted data table |
tapicker mcp | Expose a running Bridge to a local MCP client over stdio |
Run tapicker --help or tapicker <command> --help for all options.
HTTP Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
GET | /v1/health | Check Bridge health |
GET | /v1/discovery | Read Bridge metadata and the Extension WebSocket path |
GET | /v1/capabilities | Discover commands and their input schemas |
GET | /v1/extensions | List connected Extension clients |
POST | /v1/commands/{command} | Call a Workflow or data command |
| WebSocket | /v1/commands/workflow.status.watch | Subscribe to one Workflow’s status events |
| Streamable HTTP MCP | /mcp | Connect an MCP client directly to Bridge |
| WebSocket | /ws | Extension pairing and internal command transport |
/ws is for the Tapicker Extension, not an external Agent API. The full HTTP request and response format is available in the npm package’s docs/http-api.md.
Command Inputs
HTTP commands use this shape:
{
"clientId": "optional-extension-uuid",
"input": {
"workflowId": "jr657xeb"
}
}
clientId is optional only when exactly one ready Extension is connected. workflow.start also accepts an args object. The Workflow engine selects and prepares the browser tab. Data commands use tableId.
MCP Tools
extensions_list, workflow_start, workflow_pause, workflow_resume, workflow_stop, workflow_status, workflow_status_watch, workflow_logs, workflow_log, data_get, and data_delete.
data_get reads all table rows and consumes export quota. data_delete removes the selected table from Tapicker Data.
Workflow Logs
| Entry | Log list | Single log |
|---|---|---|
| CLI | tapicker workflow logs <workflowId> | tapicker workflow log <workflowId> <logId> |
| HTTP | POST /v1/commands/workflow.logs | POST /v1/commands/workflow.log |
| MCP | workflow_logs | workflow_log |
workflow.logs takes workflowId and optional levels, limit, before, after, and runAt. Levels match exactly (trace, debug, info, warn, error); omit them for all levels. Empty or invalid levels are rejected. limit defaults to 100 (1–500). Filtering happens before pagination. Without a cursor, the newest matching page is returned, always in ascending ID order. Exclusive before and after bounds read the nearest older or next newer page and cannot be combined.
The list returns { workflowId, runAt, logs, hasMore }. Each record has id, workflowId, timestamp, level, optional nodeId/nodeType, message, optional detailsText, and detailsTruncated. hasMore indicates further matches in the query direction. workflow.log takes workflowId, logId, and optional runAt, and returns { workflowId, runAt, log } with full readable details without preview truncation. Details use text representations for BigInt, Date, and circular references.
runAt is optional on every query. When supplied, it must match process.runAt or the command fails with WorkflowRunChanged. Responses always include it (null for a process that has not run). Only the latest run is retained; new runs clear old logs. Missing processes or cleared/mismatched logs return NotFound. Queries during execution read persisted logs and may lag new entries by about 500 ms. All entries support the common Extension selection options. See CLI examples.
Workflow Status Events
Connect to ws://127.0.0.1:9520/v1/commands/workflow.status.watch (use wss:// with TLS), then send a workflow.status.watch request for one workflowId. Bridge accepts the subscription and forwards workflow.status.changed events while the socket remains connected. The raw subscription does not send an initial snapshot or close automatically at a terminal state; CLI and MCP helpers read a snapshot after subscribing and finish at stopped, timeout, or cancellation.
workflow.status is the same query command from an external caller through Bridge to the Extension. workflow.status.changed is the separate event name. Capabilities list callable commands; events are documented separately.
Status snapshots and events contain workflowId, status, optional reason, and updatedAt; events also contain clientId. Status is running, paused, stopping, or stopped. Once stopping begins, pause and resume cannot reverse it, and a new run must wait for cleanup to finish.
The terminal status is stopped. The ending reason is completed for normal completion, failed for an error that stops execution, interrupted for browser/background interruption, workflow_stopped for a Stop block, or user_stopped for a UI or Bridge stop command. Only completed means successful execution; workflow_stopped is an unsuccessful ending. Handled or ignored errors can still end in completed. Active runs have no reason; unused or migrated records may also have no reason.
Events are not replayed after a disconnect; reconnect and call workflow.status once to retrieve the latest persisted snapshot. A WebSocket disconnect never stops the Workflow.
Workflow Command Errors
Command failures return { "ok": false, "error": { "code", "message", "details?" } }. CLI and MCP preserve the same error fields; failed MCP tool calls also set isError: true. Extension errors use HTTP 502; inspect error.code for the specific cause.
WorkflowNotFoundandPermissionDenied: check the Workflow ID, Extension account, and access permissions.NetworkError,RequestTimeout, andWorkflowLoadFailed: the Extension could not load the main Workflow.detailscontains diagnostic information.WorkflowAlreadyRunningandWorkflowStartInProgress: the Workflow already has an active instance or a pending start request.ProcessStopped: pause or resume is unavailable after stopping begins or without an active controller.InvalidTab,GroupTabFailed,WorkflowPrepareFailed,TableCreateFailed, andProcessUpdateFailed: the engine could not prepare browser resources, sub-workflows, local data tables, or process state.InternalError: an unexpected error occurred.
A start response confirms startup was accepted, not that execution succeeded. A stop response acknowledges the request, not that cleanup has finished. Observe status and reason for the execution result. If a start response times out, disconnects, or is invalid, reconnect as needed and query workflow.status before retrying because the command may already have taken effect.