Use the Tapicker Bridge HTTP API
Use HTTP when your application or service needs to call Tapicker directly. Complete Getting Started first: Bridge must be running, and an Extension must be paired and ready.
Examples below use the HTTP address http://127.0.0.1:9520. Replace it with the address printed by your Bridge. The curl examples use POSIX shell quoting.
1. Check the Connection
Check the service:
curl http://127.0.0.1:9520/v1/health
Then list connected Extensions:
curl http://127.0.0.1:9520/v1/extensions
The second response contains an extensions array. Choose an entry with ready: true. A healthy Bridge with no ready Extension can answer health requests but cannot run a Workflow.
A ready Extension may include a user snapshot. Call user.me to get the latest account information.
2. Start a Workflow
Copy a Workflow ID from the Extension. Replace WORKFLOW_ID and send:
curl -X POST http://127.0.0.1:9520/v1/commands/workflow.start \
-H 'Content-Type: application/json' \
-d '{"input":{"workflowId":"WORKFLOW_ID","args":{}}}'
A successful start returns a receipt like this:
{
"ok": true,
"data": {
"clientId": "c0ffee00-0000-4000-8000-000000000001",
"workflowId": "WORKFLOW_ID",
"workflowName": "@account/example",
"runAt": "2026-11-04T06:30:32.026Z",
"state": "accepted"
}
}
The Extension selects and prepares the browser tab. This receipt confirms startup was accepted. To determine the outcome, check status or subscribe to Workflow Status Events.
3. Understand Requests and Results
All business commands use POST /v1/commands/COMMAND with this body:
{
"clientId": "c0ffee00-0000-4000-8000-000000000001",
"input": { "workflowId": "WORKFLOW_ID" }
}
clientId selects an Extension. Omit it only when exactly one Extension is ready. Otherwise, select a ready entry from /v1/extensions and reuse its ID. Bridge sends a command to one Extension, never all connected browsers.
Command success uses { "ok": true, "data": RESULT }; every business result includes the actual clientId. Failure uses:
{
"ok": false,
"error": {
"code": "PermissionDenied",
"message": "Your account cannot view this Workflow."
}
}
error.details may contain field issues or other diagnostic information. Check the HTTP status and ok, then use error.code for handling. System endpoints such as /v1/extensions have their own shapes and do not use the command success envelope.
Authentication
If Bridge has a Token, add this header to protected requests:
Authorization: Bearer YOUR_TOKEN
The Token belongs to Bridge; it is different from the Extension's four-digit pairing code. For remote access and TLS, see Remote Deployment.
4. Call from JavaScript
This helper sends the same command shape from a Node.js application:
const bridgeUrl = 'http://127.0.0.1:9520'
const token = process.env.TAPICKER_BRIDGE_TOKEN
async function callTapicker(command, input, clientId) {
const response = await fetch(`${bridgeUrl}/v1/commands/${command}`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
...(token ? { Authorization: `Bearer ${token}` } : {}),
},
body: JSON.stringify({ clientId, input }),
})
const result = await response.json()
if (!response.ok || !result.ok) {
throw new Error(`${result.error?.code}: ${result.error?.message}`)
}
return result.data
}
const started = await callTapicker('workflow.start', {
workflowId: 'WORKFLOW_ID',
args: { keyword: 'Tapicker' },
})
console.log(started)
The receipt includes clientId, workflowId, the full workflowName, runAt, and state: "accepted". Use the returned clientId to check execution status. Startup uses the active browser tab as its starting point, and use-only access is sufficient to run the Workflow.
The Extension has 45 seconds to load the saved Workflow and prepare the run. Bridge waits up to 55 seconds for the Extension receipt. The CLI and MCP stdio wait up to 60 seconds for Bridge. WorkflowStartTimeout confirms the Extension canceled startup. Retry after cleanup finishes.
Set args.isClearData to the JSON boolean true only when you intend to clear existing data in the affected tables. A duplicate start returns HTTP 409 with WorkflowStartInProgress, WorkflowAlreadyRunning, or WorkflowCleanupInProgress while the Extension cleans up a failed start. If the start response is lost, check status on the same Extension before retrying.
Find and Author Workflows
Start with saved content, then use the authoring commands if you need to create or change nodes:
| Command | input | Result inside data |
|---|---|---|
workflow.guide | Optional topic, default overview | topic, Markdown content, references |
workflow.schema | Optional non-empty nodeTypes array | A self-contained JSON Schema in schema |
workflow.validate | fragment as parsed JSON | isValid: true and normalized nodes when supplied, or isValid: false and issues |
workflow.list | Optional scope, name, host, page, pageSize | workflows summaries and pagination fields |
workflow.get | workflowId | Metadata, startup arguments, and nodes when permitted |
workflow.create | name, nodes; optional intro, href | workflowId, workflowName, revision when supported |
workflow.update | workflowId, revision, and at least one editable field | workflowId and the new revision |
Each result also includes clientId. List scopes are own (default), shared, and pinned; name matches a substring of fullname. page starts at 1; pageSize defaults to 20 and accepts 1–100. An empty page ends pagination. Pinned entries can include deleted Workflows, indicated by deletedAt; do not run or edit deleted entries.
List entries contain id, fullname, intro, host, href, visibility, permission, version, revision when supported, and deletedAt. They do not contain name or nodes. Use each id as workflowId for later commands.
To filter one site, send input: { "host": "example.com" } to workflow.list. host matches the stored host exactly, without a scheme or path; it may include a port such as localhost:3000. example.com and www.example.com are different hosts. A site filter excludes generic Workflows whose host is *; host: "*" selects only those. Omit host for all sites. name and host filters are combined before pagination, across all three scopes. The response shape is unchanged, and each summary includes its host.
Pass an id from workflow.list as workflowId to read the latest saved Workflow. The result includes metadata, args, nodes, and icon in workflow. With use permission, nodes is empty because the saved nodes are hidden. With view, edit, or manage permission, it contains the saved nodes. A missing, deleted, or inaccessible Workflow returns HTTP 404.
Each item in workflow.args contains name and type, with label, placeholder, options, and defaultValue when available. If the Workflow has an enabled Extract Data node configured to save data, the array includes the boolean isClearData option with a default of false. A Workflow with no startup arguments returns args: []. Argument defaults are visible to users who can run the Workflow.
Validate and Create
Read workflow.guide with input: {} first. Follow its references.topic values using the same command. For workflow.schema, pass the node types you plan to use in input.nodeTypes, for example ["NodeLoop", "NodeExtractData"]; omit nodeTypes to get the schema for all supported business nodes. The returned schema is a draft 2020-12 JSON Schema for version 1 clipboard documents and contains the definitions it needs. Schema defaults do not fill omitted fields; check generated fragments with workflow.validate.
Send a parsed clipboard document in input.fragment:
{
"input": {
"fragment": {
"format": "tapicker/nodes",
"version": 1,
"nodes": [
{
"id": "hello",
"type": "NodePrintLog",
"config": { "level": "info", "message": "Hello from HTTP" }
}
]
}
}
}
Use tapicker/workflow with a workflow object to validate any supplied name, intro, href, or nodes. The object must include at least one of those fields. Both document formats use version: 1.
Invalid fragment content returns HTTP 200 with ok: true and data.isValid: false. Inspect issues and repair the reported fields. A missing fragment or invalid request shape instead fails the command. Static validation does not verify page selectors or actual execution.
With data.isValid: true, data.nodes contains normalized copies if the input includes nodes. Normalization can trim names, remove inapplicable fields, and apply retry defaults when retry is enabled. Pass the normalized array as top-level nodes in create or update requests.
To create a private Workflow, send name and nodes to workflow.create. name is trimmed and must contain 1–64 characters. Optional intro and href default to empty. href accepts an absolute URL (for example, https://example.com, file:///path/to/page.html, or about:blank) or an empty string for a general-purpose Workflow. The name must be available in the selected account.
Creation validates and saves without running. The result includes clientId and the full name in workflowName, such as @username/example. For node validation errors, inspect error.details.issues. If the response is lost, call workflow.list with scope: "own" and the requested name on the same Extension, then use workflow.get to verify matching content before retrying. To automate a local page, enable Allow access to file URLs in the Extension settings.
Update with a Revision
Call workflow.get, then submit its workflow.revision unchanged and reuse the returned clientId:
curl -X POST http://127.0.0.1:9520/v1/commands/workflow.update \
-H 'Content-Type: application/json' \
-d '{"clientId":"c0ffee00-0000-4000-8000-000000000001","input":{"workflowId":"WORKFLOW_ID","revision":3,"intro":"Updated through HTTP"}}'
Replace the example Workflow ID, revision, and client ID with the values you read. Editable fields are name, intro, href, and nodes; at least one is required. Omitted fields stay unchanged. Set intro or href to an empty string to clear it. A non-empty href follows the same rules as creation. Supplying nodes replaces the entire node tree after validation. Update requires edit/manage permission and revision support on the Workflow server. It neither starts the Workflow nor changes a running instance.
A conflicting edit returns HTTP 409 WorkflowConflict, with the revision observed at detection in error.details.revision. Read again, reconcile content, and submit the revision of that new read. Do not blindly swap revision numbers or retry; there is no force flag. If an update times out, read first to check whether it took effect.
Run and Control Workflows
| Command | input | Purpose |
|---|---|---|
workflow.start | workflowId, optional args object | Start one instance and return a receipt |
workflow.pause | workflowId | Pause the active instance |
workflow.resume | workflowId | Resume it |
workflow.stop | workflowId | Request a stop |
workflow.status | workflowId; optional runAt, includeDataSummary | Read the latest recorded status snapshot |
Use workflow.get to discover the startup arguments. If it declares { "name": "keyword", "type": "string" }, send input: { "workflowId": "WORKFLOW_ID", "args": { "keyword": "Tapicker" } } to workflow.start. Use the exact declared names, omit values to use defaults, and reuse the same clientId.
The control receipts contain clientId and workflowId. Reuse the IDs from the start receipt. Pause takes effect at the next pause point, and resume continues the same instance. Repeating pause on a paused instance or resume on a running instance succeeds. Stop requests cancellation of a running or paused instance and succeeds when there is no active instance. Wait for stopped to confirm cleanup. The API returns HTTP 409 with WorkflowStartInProgress while the instance is initializing, or ProcessStopped when pause or resume cannot apply because the run is stopping or has ended.
Single status queries return clientId, workflowId, status, createdAt, and updatedAt. They also include workflowName, reason, runAt, and stopAt when recorded. createdAt is the creation time of the status record. runAt and stopAt describe the latest run. runAt identifies the run and can be passed to workflow.logs to check that the logs belong to it. During startup preparation, the snapshot can still describe the previous run. If the selected Extension has no status record, the API returns HTTP 404 with NotFound. Status is running, paused, stopping, or stopped. Only status: "stopped" with reason: "completed" means success. Other terminal reasons are failed, interrupted, workflow_stopped, and user_stopped. Unused or older records may have no reason.
After a run stops, pass includeDataSummary: true and the observed runAt to workflow.status. The result's dataSummary groups changes by tableId, with tableName, insertedCount, updatedCount, and deletedCount. It includes committed changes from child Workflows and from runs that failed or were stopped. Counts describe row operations, so repeated changes to the same row may count more than once. Startup clearing via args.isClearData is excluded.
An empty summary means the run recorded no row changes. The field is omitted if a saved summary is unavailable. If runAt has changed, the API returns HTTP 409 WorkflowRunChanged. Use data.get with the returned table and client IDs to read saved rows.
Workflow Status Events
For ongoing updates, use the WebSocket endpoint:
ws://127.0.0.1:9520/v1/commands/workflow.status.watch
Use wss:// remotely. If Bridge requires a Token, include Authorization: Bearer YOUR_TOKEN in the WebSocket handshake using a client that supports custom headers.
After connecting, send this request envelope. Use a unique id and the current Unix time in milliseconds for time:
{
"id": "watch-1",
"time": 1720000000000,
"type": "workflow.status.watch",
"data": { "input": { "workflowId": "WORKFLOW_ID" } }
}
When necessary, include clientId in data, beside input. Bridge replies with the same id, type workflow.status.watch:res, and data: { ok: true, data: { clientId, workflowId } }. Failures use data: { ok: false, error }.
Then it sends envelopes of type workflow.status.changed; each envelope's data is a status snapshot including clientId. A stopped event also includes stopAt when recorded. The raw subscription has no initial snapshot, replay, or automatic close at completion.
For an existing run, subscribe first and then query workflow.status once using the accepted clientId. To observe a new run, subscribe before calling workflow.start on that same client. Match the events’ runAt to the start receipt to identify the new run. Close your subscription after that run reaches stopped or when you no longer need it. Reconnect and read one fresh snapshot after a disconnect. Closing a subscription does not stop execution.
Workflow Logs
Use workflow.logs when investigating a run, rather than continuously polling logs:
{ "input": { "workflowId": "WORKFLOW_ID", "levels": ["warn", "error"], "limit": 100 } }
The result contains clientId, workflowId, runAt, logs, and hasMore. Supported levels are trace, debug, info, warn, and error; omit levels for all. limit defaults to 100 and accepts 1–500. Optional before and after are exclusive positive log IDs and cannot be combined. Without either, the newest matching page is returned, always in ascending ID order.
Each log has id, workflowId, timestamp, level, message, detailsTruncated, and optional nodeId, nodeType, and detailsText. For workflow-level entries, nodeType is Workflow and nodeId is the workflow ID. Lifecycle messages for these entries are Started, Completed, or Failed. detailsText is capped at 1,024 characters per list entry. If detailsTruncated is true, pass the entry’s id as logId to workflow.log for full readable details. Reuse workflowId, clientId, and non-null runAt. The single-log result also contains clientId, workflowId, and runAt.
Both commands accept an optional non-null runAt from an earlier result to require that same run. Only the latest run is retained; new runs clear old logs. Missing or cleared logs return NotFound; a changed run returns HTTP 409 with WorkflowRunChanged. Check workflow.status before choosing which run to inspect. During execution, recently written logs may briefly lag actual progress.
List, Preview, Read, Export, and Delete Data
Use the table ID copied from Tapicker Data:
| Command | input | Result inside data, plus clientId |
|---|---|---|
data.list | Optional tableName, workflowId, page, and pageSize | List saved table metadata |
data.preview | tableId; optional sample | Preview up to 10 rows without using export quota |
data.get | tableId; optional page, pageSize, or all: true | Read saved rows |
data.export | tableId; optional format | Export the full table to a file |
data.delete | tableId | tableId and tableName |
data.list returns clientId, page, pageSize, hasMore, and tables. Each table includes tableId, tableName, columnNames, rowCount, createdAt, updatedAt, and workflowId when known. columnNames lists the currently registered column names in table order. Older rows may lack columns that were added later. Tables with no registered columns return columnNames: [].
tableName matches a case-insensitive substring and workflowId matches the exact owner. Both filters apply when provided together. Results are ordered by most recently updated. The default is page 1 with 20 tables, with a maximum of 100 per page. Listing uses no export quota.
Call data.preview with input: { "tableId": "TABLE_ID", "sample": "latest" } to inspect the most recently inserted rows. Omit sample or set it to oldest to inspect the earliest rows. Both samples return up to 10 rows in ascending row ID order and use no export quota. The result includes clientId, tableId, tableName, columnNames, rowCount, rows, sample, and isTruncated.
If a row would exceed the 128 KiB preview limit, the result returns the complete rows that fit before it and sets isTruncated: true. If the first row exceeds the limit, rows is empty and isTruncated is true.
By default, data.get returns page 1 with 50 rows in ascending row ID order. pageSize accepts 1–500. The result includes clientId, tableId, tableName, columnNames, rowCount, and rows. In both preview and read results, rowCount is the total recorded in table metadata. Use rows.length for the number returned. Paged results also include page, pageSize, and hasMore. For all rows, send all: true and omit pagination fields.
For data.get, only returned rows count against export quota. A result over 128 KiB returns HTTP 413 DataResultTooLarge before quota is deducted. Use a smaller page size or switch from full-table mode to pagination. Insufficient quota returns HTTP 403 ExportQuotaExceeded. If the response is lost, check before retrying because quota may already have been deducted.
To export a table, call data.export with its tableId and optional format. Supported formats are xlsx, xls, csv, json, xml, and txt. The default is csv. The receipt contains clientId, tableId, tableName, format, filename, rowCount, byteSize, fileSize, downloadPath, and expiresAt. byteSize is the exact size in bytes. fileSize uses B, K, M, and G without a space, such as 850B or 1.5K. One K is 1,024 bytes.
Fetch downloadPath with GET on the same Bridge using the same authorization, and save the response body as a file. Each export is capped at 128 MiB. Files remain available for 24 hours, including across Bridge restarts that use the same data directory. Exporting consumes row quota once. You can download the same file again before it expires. If the command response is lost, quota may already have been deducted. If you receive ExportStorageFull, retry after earlier exports expire.
data.delete removes a saved table and all its rows from the selected Extension. Use the ID from Copy ID in Tapicker Data. The receipt includes clientId, tableId, and tableName. HTTP 409 DataTableInUse means another operation is using the table. Wait for it to finish. If the response is lost, verify the table before retrying because a later Workflow run can recreate it under the same ID.
Read the Current Tapicker Account
Call POST /v1/commands/user.me with { "input": {} }. Include clientId in the request when multiple Extensions are ready.
The result contains clientId and user with id, username, and plan (Free, Plus, or Pro). An unverified email or a banned account returns EmailNotVerified or AccountBanned. Network failures and timeouts return errors.
Endpoint and Error Reference
| Method or transport | Path | Purpose |
|---|---|---|
| GET | /v1/health | Service health; public |
| GET | /v1/discovery | Service addresses and authentication metadata; public |
| GET | /v1/capabilities | Command descriptions and input/output schemas; public |
| GET | /v1/extensions | Connected clients and readiness; protected when a Token is set |
| POST | /v1/commands/COMMAND | Workflow or data command |
| WebSocket | /v1/commands/workflow.status.watch | Status subscription |
| Streamable HTTP | /mcp | Direct agent connection, described in MCP |
| WebSocket | /ws | Extension connection and pairing |
/ws is for the Extension; applications use command endpoints or the status subscription. A normal HTTP request to the status WebSocket path returns 405 WebSocketRequired.
| HTTP status | Common codes | What to do |
|---|---|---|
| 400 | InvalidArguments, InvalidJson | Correct the request; inspect field issues when present |
| 401 | Unauthorized | Supply the Bridge Token |
| 403 | SignInRequired | Sign in to Tapicker in the selected Extension |
| 403 | EmailNotVerified, AccountBanned | Check the Tapicker account status |
| 403 | PermissionDenied | Check permissions for the requested operation |
| 404 | NotFound, WorkflowNotFound, CommandNotFound | Check the resource or command name |
| 409 | WorkflowConflict, ClientIdRequired, ExtensionNotConnected, ExtensionCapabilityUnavailable | Reconcile the edit or select a ready, compatible Extension |
| 502 | InvalidExtensionResponse, NetworkError, other Extension failures | Inspect error.code, message, and details |
| 503 | ExtensionUnavailable | Connect and pair an Extension |
| 504 | ExtensionRequestTimeout, RequestTimeout | Check status or saved content before retrying a write |
| 504 | WorkflowStartTimeout | Startup was canceled. Wait for cleanup before retrying. |
Server business errors can return additional codes. Use error.code to identify the condition and error.message for its explanation. For example, a server-side plan restriction can include a specific code with HTTP 403. HTTP 401 Unauthorized identifies Bridge Token authentication.
Execution failures after an accepted start are reported through status and logs. If a start response is lost, query status before retrying. In browser-based integrations, CORS is separate from authentication; see Remote Deployment for configuration.