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

CommandPurpose
tapicker bridge start [--daemon]Start Bridge in the foreground or in the background
tapicker bridge stopStop a background Bridge
tapicker bridge code [--refresh]Show or rotate the Extension pairing code
tapicker bridge extensionsList 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> --watchWait 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 mcpExpose a running Bridge to a local MCP client over stdio

Run tapicker --help or tapicker <command> --help for all options.

HTTP Endpoints

MethodEndpointPurpose
GET/v1/healthCheck Bridge health
GET/v1/discoveryRead Bridge metadata and the Extension WebSocket path
GET/v1/capabilitiesDiscover commands and their input schemas
GET/v1/extensionsList connected Extension clients
POST/v1/commands/{command}Call a Workflow or data command
WebSocket/v1/commands/workflow.status.watchSubscribe to one Workflow’s status events
Streamable HTTP MCP/mcpConnect an MCP client directly to Bridge
WebSocket/wsExtension 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

EntryLog listSingle log
CLItapicker workflow logs <workflowId>tapicker workflow log <workflowId> <logId>
HTTPPOST /v1/commands/workflow.logsPOST /v1/commands/workflow.log
MCPworkflow_logsworkflow_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.

  • WorkflowNotFound and PermissionDenied: check the Workflow ID, Extension account, and access permissions.
  • NetworkError, RequestTimeout, and WorkflowLoadFailed: the Extension could not load the main Workflow. details contains diagnostic information.
  • WorkflowAlreadyRunning and WorkflowStartInProgress: 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, and ProcessUpdateFailed: 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.