REST API

Web

Derived from the source of github.com/awee-ai/api/cmd/web.

Awee Web API · v1.0.0 · 7 endpoints

Extension

GET/v1/extension/clientsAuth

Lists every extension the bridge knows about

ext.DispatchHandler.Clients

Takes no parameters and no request body.

Responses

200 OKOK
connectedbooleanrequired

Reflects whether a live SSE stream is currently open for it.

connected_atstring (date-time)

Is when the current connection was established.

helloHelloInfo

Is the handshake the extension sends when it connects, announcing who it is and what it can do so the server can route work it supports.

actionsstring[]

Lists the step types this extension build can execute.

browserstring

Names the browser the extension runs in.

messagesMessageType[]

Advertises the envelope types the extension understands, so this side can feature-detect the config/sequence flow and fall back to inline run against an older extension.

rolestring

Identifies the peer kind, "extension" for the browser extension.

versionstring

Is the extension build version.

idstringrequired

Is the client id the extension registered under.

last_seenstring (date-time)

Is the last time the extension connected, disconnected, or sent a message.

500 Internal Server Errorthe request could not be completed
errorstringrequired
Defaultthe request could not be completed
errorstringrequired
Request

No request body.

200 OK
[
  {
    "connected": true,
    "connected_at": "2024-01-15T09:30:00Z",
    "hello": {
      "actions": [
        "string"
      ],
      "browser": "string",
      "messages": [
        "string"
      ],
      "role": "string",
      "version": "string"
    },
    "id": "string",
    "last_seen": "2024-01-15T09:30:00Z"
  }
]
GET/v1/extension/eventsAuth

Upgrades the request to an SSE stream and pushes every Message queued for this client until the connection drops

The client identifies itself with the client_id query parameter.

ext.Handler.Events

Query parameters

client_idstring

Responses

200 OKOK
string
400 Bad Requestthe request could not be completed
errorstringrequired
403 Forbiddenthe request could not be completed
errorstringrequired
Defaultthe request could not be completed
errorstringrequired
Request

No request body.

200 OK
"string"
POST/v1/extension/messagesAuth

Accepts one inbound Message from the extension and routes it by type to the broker and backend

It replies 200 with an empty ack body on success so the extension knows the message landed. Unknown or push-only types are rejected with 400. The envelope id rides along to the backend so a dispatcher can correlate result and error replies to the push that caused them.

ext.Handler.Messages

Query parameters

client_idstring

Body

application/jsonrequired
configLibrarySync

Is a server push of the canonical fragment set.

replaceboolean

Swaps the whole library for Workflows (pruning fragments no longer shipped) instead of the default merge-by-id.

workflowsWorkflow[]

Are the fragments to install in the extension's library.

conditionCondition

Gates whether a workflow or step runs.

matchstring

Decides how the set predicates combine, "any" or "all".

negateboolean

Inverts the combined result.

selectorstring

Holds when a matching element exists on the page.

textstring

Holds when the page (or the selected element) contains this text.

url_includesstring

Holds when the page URL contains this substring.

idstring

Uniquely names the workflow.

namestring

Is the human-readable title shown in the extension UI.

optionsWorkflowOptions

Carries run-wide defaults for a workflow.

concurrencystring

Is the contention policy when another run already holds the target tab, one of "queue" (default), "parallel", or "reject".

continue_on_errorboolean

Keeps the run going past a failed step instead of stopping at the first failure.

default_timeout_msinteger (int64)

Is the per-step timeout in milliseconds for steps that do not set their own.

stepsStep[]

Are the actions to perform, in order.

argsunknown[]

Are the arguments passed to Fn.

attributestring

Names the DOM attribute an extraction step reads.

body_paramsobject

Overrides or adds form fields on the re-issued request of a captureDownload step.

*stringany additional property
conditionCondition

Gates whether a workflow or step runs.

matchstring

Decides how the set predicates combine, "any" or "all".

negateboolean

Inverts the combined result.

selectorstring

Holds when a matching element exists on the page.

textstring

Holds when the page (or the selected element) contains this text.

url_includesstring

Holds when the page URL contains this substring.

continue_onContinueCondition

Holds a step until a user gate is cleared or a page condition is met.

manualboolean

Pauses the run for an explicit user continue.

selectorstring

Resumes when a matching element appears.

textstring

Resumes when this text is present on the page.

timeout_msinteger (int64)

Bounds the hold, in milliseconds.

url_includesstring

Resumes when the page URL contains this substring.

filenamestring

Renames a captured file (captureDownload).

fnstring

Names the page function an eval step invokes.

formatstring

Names the shape extraction steps return their data in.

idstring

Uniquely names the step within its workflow, echoed on its StepResult.

labelstring

Is a human-readable description shown in run progress UIs.

optionalboolean

Lets the run continue when this step fails.

outputstring

Chooses where a captured file goes, the transport or disk.

promptstring

Is the text shown at a user gate asking for manual input.

selectorSelector

Picks the DOM node(s) a step acts on, by CSS or an explicit path, optionally narrowed to specific indexes or expanded to all matches.

allboolean

Expands the step to act on every match instead of the first.

cssstring

Is a CSS selector.

indexinteger (int64)

Narrows a multi-match selector to a single position.

indexesinteger (int64)[]

Narrows a multi-match selector to these positions.

pathstring

Is an explicit DOM path, used when CSS cannot express the target.

storestring

Names a slot the step's data is saved under, readable by later steps and returned on the WorkflowResult.

timeout_msinteger (int64)

Overrides the workflow's default step timeout, in milliseconds.

typestring

Is the action to perform (click, fill, select, captureDownload, ...).

urlstring

Is the address for navigation steps.

valuestring

Is the input for value-taking steps such as fill and select.

waitWaitConfig

Makes a step block until a page condition holds.

absentboolean

Flips the wait to expect the selector to disappear rather than appear.

delay_msinteger (int64)

Is a fixed pause in milliseconds, applied on top of any condition.

selectorstring

Waits for a matching element to appear (or disappear, see Absent).

textstring

Waits for this text to be present on the page.

timeout_msinteger (int64)

Bounds the wait, in milliseconds.

url_includesstring

Waits for the page URL to contain this substring.

targetTargetConfig

Locates the page a workflow runs against and controls how the tab hosting it is managed.

activateboolean

Brings the target tab to the foreground.

match_urlstring

Is a substring an existing tab's URL must contain for the run to reuse that tab instead of opening URL.

reloadboolean

Forces a page reload on a reused tab before the first step runs.

reuse_tabboolean

Reuses a matching open tab instead of opening a new one.

urlstring

Is the address to open when no existing tab matches.

errorstring

Is the failure description on an error message, set alongside the ID of the push that failed.

eventRunEvent

Is a progress signal streamed during a run so the server can follow along step by step.

messagestring

Is free-form detail, set on gate and error events.

resultStepResult

Is the outcome of a single step, reported back by the extension.

dataunknown

Is the step's extracted output, if any.

errorstring

Describes the failure when OK is false.

fileCapturedFile

Is a file a step produced, inlined in a StepResult.

datastring (byte)

Is the raw file content.

filenamestring

Is the file's name, after any step-level rename.

mimestring

Is the file's content type.

sizeinteger (int64)

Is the byte length of Data.

finished_atinteger (int64)

Is when the step ended, in Unix milliseconds.

formatstring

Names the shape Data is in.

okboolean

Reports whether the step succeeded.

skippedboolean

Is true when the step's condition was not met, so it neither ran nor failed.

started_atinteger (int64)

Is when the step began, in Unix milliseconds.

step_idstring

Is the id of the step this result belongs to.

typestring

Echoes the step's action type.

run_idstring

Is the run instance these events belong to, distinct from WorkflowID so the same workflow fired twice yields two tellable streams.

sequence_idstring

And SequenceIndex are set when the run is a fragment of a sequence, tying its events to the whole job and its position in it.

sequence_indexinteger (int64)
step_idstring

And StepIndex identify the step a step-scoped event refers to.

step_indexinteger (int64)
typestring

Is one of the run lifecycle markers (workflow:start, step:end, user:gate, and so on).

workflow_idstring

Is the workflow the event belongs to.

workflow_resultWorkflowResult

Is the terminal outcome of a whole workflow run.

errorstring

Describes what stopped the run when OK is false.

finished_atinteger (int64)

Is when the run ended, in Unix milliseconds.

okboolean

Reports whether the run succeeded.

started_atinteger (int64)

Is when the run began, in Unix milliseconds.

stepsStepResult[]

Holds each step's result, in run order.

dataunknown

Is the step's extracted output, if any.

errorstring

Describes the failure when OK is false.

fileCapturedFile

Is a file a step produced, inlined in a StepResult.

datastring (byte)

Is the raw file content.

filenamestring

Is the file's name, after any step-level rename.

mimestring

Is the file's content type.

sizeinteger (int64)

Is the byte length of Data.

finished_atinteger (int64)

Is when the step ended, in Unix milliseconds.

formatstring

Names the shape Data is in.

okboolean

Reports whether the step succeeded.

skippedboolean

Is true when the step's condition was not met, so it neither ran nor failed.

started_atinteger (int64)

Is when the step began, in Unix milliseconds.

step_idstring

Is the id of the step this result belongs to.

typestring

Echoes the step's action type.

storedobject

Holds the values the workflow's store steps captured, keyed by store name, so a sequence chains one fragment's output into the next and a caller can read them.

workflow_idstring

Is the id of the workflow this result belongs to.

fileFilePayload

Is a file uploaded out of band via the messages endpoint rather than inlined in a result, for payloads too large to ride along a StepResult.

datastring (byte)

Is the raw file content.

filenamestring

Is the file's name, after any step-level rename.

mimestring

Is the file's content type.

run_idstring

Ties a captured file to the run that produced it; SequenceID ties it to the sequence that drove the fragment, set only for a sequence run.

sequence_idstring
sizeinteger (int64)

Is the byte length of Data.

step_idstring

Is the step that captured the file.

workflow_idstring

Is the workflow whose step produced the file.

helloHelloInfo

Is the handshake the extension sends when it connects, announcing who it is and what it can do so the server can route work it supports.

actionsstring[]

Lists the step types this extension build can execute.

browserstring

Names the browser the extension runs in.

messagesMessageType[]

Advertises the envelope types the extension understands, so this side can feature-detect the config/sequence flow and fall back to inline run against an older extension.

rolestring

Identifies the peer kind, "extension" for the browser extension.

versionstring

Is the extension build version.

idstring

Correlates a push with its reply.

resultWorkflowResult

Is the terminal outcome of a whole workflow run.

errorstring

Describes what stopped the run when OK is false.

finished_atinteger (int64)

Is when the run ended, in Unix milliseconds.

okboolean

Reports whether the run succeeded.

started_atinteger (int64)

Is when the run began, in Unix milliseconds.

stepsStepResult[]

Holds each step's result, in run order.

dataunknown

Is the step's extracted output, if any.

errorstring

Describes the failure when OK is false.

fileCapturedFile

Is a file a step produced, inlined in a StepResult.

datastring (byte)

Is the raw file content.

filenamestring

Is the file's name, after any step-level rename.

mimestring

Is the file's content type.

sizeinteger (int64)

Is the byte length of Data.

finished_atinteger (int64)

Is when the step ended, in Unix milliseconds.

formatstring

Names the shape Data is in.

okboolean

Reports whether the step succeeded.

skippedboolean

Is true when the step's condition was not met, so it neither ran nor failed.

started_atinteger (int64)

Is when the step began, in Unix milliseconds.

step_idstring

Is the id of the step this result belongs to.

typestring

Echoes the step's action type.

storedobject

Holds the values the workflow's store steps captured, keyed by store name, so a sequence chains one fragment's output into the next and a caller can read them.

workflow_idstring

Is the id of the workflow this result belongs to.

sequenceRunSequence

Is an ordered list of fragment references run as one logical job.

idstring

Is the sequence/run id (falls back to the Message id).

optionsSequenceOptions

Tunes how a sequence handles a fragment failure.

continue_on_errorboolean

Keeps the sequence going after a fragment fails instead of stopping at the first failure.

refsSequenceRef[]

Are the library fragments to run, in order.

variablesobject

Apply to this fragment only, merged over the sequence-wide bag.

*stringany additional property
workflow_idstring

Is the id of the library fragment to run.

sequence_resultSequenceResult

Is the outcome of a whole sequence, each fragment's result in run order plus the combined ok/error.

errorstring

Describes what stopped the sequence when OK is false.

finished_atinteger (int64)

Is when the sequence ended, in Unix milliseconds.

okboolean

Reports whether every fragment succeeded.

sequence_idstring

Is the id of the sequence these results belong to.

started_atinteger (int64)

Is when the sequence began, in Unix milliseconds.

workflowsWorkflowResult[]

Holds each fragment's result, in run order.

errorstring

Describes what stopped the run when OK is false.

finished_atinteger (int64)

Is when the run ended, in Unix milliseconds.

okboolean

Reports whether the run succeeded.

started_atinteger (int64)

Is when the run began, in Unix milliseconds.

stepsStepResult[]

Holds each step's result, in run order.

dataunknown

Is the step's extracted output, if any.

errorstring

Describes the failure when OK is false.

fileCapturedFile

Is a file a step produced, inlined in a StepResult.

datastring (byte)

Is the raw file content.

filenamestring

Is the file's name, after any step-level rename.

mimestring

Is the file's content type.

sizeinteger (int64)

Is the byte length of Data.

finished_atinteger (int64)

Is when the step ended, in Unix milliseconds.

formatstring

Names the shape Data is in.

okboolean

Reports whether the step succeeded.

skippedboolean

Is true when the step's condition was not met, so it neither ran nor failed.

started_atinteger (int64)

Is when the step began, in Unix milliseconds.

step_idstring

Is the id of the step this result belongs to.

typestring

Echoes the step's action type.

storedobject

Holds the values the workflow's store steps captured, keyed by store name, so a sequence chains one fragment's output into the next and a caller can read them.

workflow_idstring

Is the id of the workflow this result belongs to.

typeMessageTyperequired

Names the payload an envelope carries.

variablesobject

Are per-run values injected by this side, overriding the extension's stored defaults.

*stringany additional property
workflowWorkflow

Is one automation run the extension should perform against a page.

conditionCondition

Gates whether a workflow or step runs.

matchstring

Decides how the set predicates combine, "any" or "all".

negateboolean

Inverts the combined result.

selectorstring

Holds when a matching element exists on the page.

textstring

Holds when the page (or the selected element) contains this text.

url_includesstring

Holds when the page URL contains this substring.

idstring

Uniquely names the workflow.

namestring

Is the human-readable title shown in the extension UI.

optionsWorkflowOptions

Carries run-wide defaults for a workflow.

concurrencystring

Is the contention policy when another run already holds the target tab, one of "queue" (default), "parallel", or "reject".

continue_on_errorboolean

Keeps the run going past a failed step instead of stopping at the first failure.

default_timeout_msinteger (int64)

Is the per-step timeout in milliseconds for steps that do not set their own.

stepsStep[]

Are the actions to perform, in order.

argsunknown[]

Are the arguments passed to Fn.

attributestring

Names the DOM attribute an extraction step reads.

body_paramsobject

Overrides or adds form fields on the re-issued request of a captureDownload step.

*stringany additional property
conditionCondition

Gates whether a workflow or step runs.

matchstring

Decides how the set predicates combine, "any" or "all".

negateboolean

Inverts the combined result.

selectorstring

Holds when a matching element exists on the page.

textstring

Holds when the page (or the selected element) contains this text.

url_includesstring

Holds when the page URL contains this substring.

continue_onContinueCondition

Holds a step until a user gate is cleared or a page condition is met.

manualboolean

Pauses the run for an explicit user continue.

selectorstring

Resumes when a matching element appears.

textstring

Resumes when this text is present on the page.

timeout_msinteger (int64)

Bounds the hold, in milliseconds.

url_includesstring

Resumes when the page URL contains this substring.

filenamestring

Renames a captured file (captureDownload).

fnstring

Names the page function an eval step invokes.

formatstring

Names the shape extraction steps return their data in.

idstring

Uniquely names the step within its workflow, echoed on its StepResult.

labelstring

Is a human-readable description shown in run progress UIs.

optionalboolean

Lets the run continue when this step fails.

outputstring

Chooses where a captured file goes, the transport or disk.

promptstring

Is the text shown at a user gate asking for manual input.

selectorSelector

Picks the DOM node(s) a step acts on, by CSS or an explicit path, optionally narrowed to specific indexes or expanded to all matches.

allboolean

Expands the step to act on every match instead of the first.

cssstring

Is a CSS selector.

indexinteger (int64)

Narrows a multi-match selector to a single position.

indexesinteger (int64)[]

Narrows a multi-match selector to these positions.

pathstring

Is an explicit DOM path, used when CSS cannot express the target.

storestring

Names a slot the step's data is saved under, readable by later steps and returned on the WorkflowResult.

timeout_msinteger (int64)

Overrides the workflow's default step timeout, in milliseconds.

typestring

Is the action to perform (click, fill, select, captureDownload, ...).

urlstring

Is the address for navigation steps.

valuestring

Is the input for value-taking steps such as fill and select.

waitWaitConfig

Makes a step block until a page condition holds.

absentboolean

Flips the wait to expect the selector to disappear rather than appear.

delay_msinteger (int64)

Is a fixed pause in milliseconds, applied on top of any condition.

selectorstring

Waits for a matching element to appear (or disappear, see Absent).

textstring

Waits for this text to be present on the page.

timeout_msinteger (int64)

Bounds the wait, in milliseconds.

url_includesstring

Waits for the page URL to contain this substring.

targetTargetConfig

Locates the page a workflow runs against and controls how the tab hosting it is managed.

activateboolean

Brings the target tab to the foreground.

match_urlstring

Is a substring an existing tab's URL must contain for the run to reuse that tab instead of opening URL.

reloadboolean

Forces a page reload on a reused tab before the first step runs.

reuse_tabboolean

Reuses a matching open tab instead of opening a new one.

urlstring

Is the address to open when no existing tab matches.

Responses

200 OKOK
*stringany additional property
400 Bad Requestthe request could not be completed
errorstringrequired
403 Forbiddenthe request could not be completed
errorstringrequired
500 Internal Server Errorthe request could not be completed
errorstringrequired
Defaultthe request could not be completed
errorstringrequired
Request body
{
  "config": {
    "replace": true,
    "workflows": [
      {
        "condition": {
          "match": "string",
          "negate": true,
          "selector": "string",
          "text": "string",
          "url_includes": "string"
        },
        "id": "string",
        "name": "string",
        "options": {
          "concurrency": "string",
          "continue_on_error": true,
          "default_timeout_ms": 0
        },
        "steps": [
          {
            "args": [
              null
            ],
            "attribute": "string",
            "body_params": {
              "key": "string"
            },
            "condition": {
              "match": "string",
              "negate": true,
              "selector": "string",
              "text": "string",
              "url_includes": "string"
            },
            "continue_on": {
              "manual": true,
              "selector": "string",
              "text": "string",
              "timeout_ms": 0,
              "url_includes": "string"
            },
            "filename": "string",
            "fn": "string",
            "format": "string",
            "id": "string",
            "label": "string",
            "optional": true,
            "output": "string",
            "prompt": "string",
            "selector": {
              "all": true,
              "css": "string",
              "index": 0,
              "indexes": [
                0
              ],
              "path": "string"
            },
            "store": "string",
            "timeout_ms": 0,
            "type": "string",
            "url": "string",
            "value": "string",
            "wait": {
              "absent": true,
              "delay_ms": 0,
              "selector": "string",
              "text": "string",
              "timeout_ms": 0,
              "url_includes": "string"
            }
          }
        ],
        "target": {
          "activate": true,
          "match_url": "string",
          "reload": true,
          "reuse_tab": true,
          "url": "string"
        }
      }
    ]
  },
  "error": "string",
  "event": {
    "message": "string",
    "result": {
      "data": null,
      "error": "string",
      "file": {
        "data": "aGVsbG8=",
        "filename": "string",
        "mime": "string",
        "size": 0
      },
      "finished_at": 0,
      "format": "string",
      "ok": true,
      "skipped": true,
      "started_at": 0,
      "step_id": "string",
      "type": "string"
    },
    "run_id": "string",
    "sequence_id": "string",
    "sequence_index": 0,
    "step_id": "string",
    "step_index": 0,
    "type": "string",
    "workflow_id": "string",
    "workflow_result": {
      "error": "string",
      "finished_at": 0,
      "ok": true,
      "started_at": 0,
      "steps": [
        {
          "data": null,
          "error": "string",
          "file": {
            "data": "aGVsbG8=",
            "filename": "string",
            "mime": "string",
            "size": 0
          },
          "finished_at": 0,
          "format": "string",
          "ok": true,
          "skipped": true,
          "started_at": 0,
          "step_id": "string",
          "type": "string"
        }
      ],
      "stored": {},
      "workflow_id": "string"
    }
  },
  "file": {
    "data": "aGVsbG8=",
    "filename": "string",
    "mime": "string",
    "run_id": "string",
    "sequence_id": "string",
    "size": 0,
    "step_id": "string",
    "workflow_id": "string"
  },
  "hello": {
    "actions": [
      "string"
    ],
    "browser": "string",
    "messages": [
      "string"
    ],
    "role": "string",
    "version": "string"
  },
  "id": "string",
  "result": {
    "error": "string",
    "finished_at": 0,
    "ok": true,
    "started_at": 0,
    "steps": [
      {
        "data": null,
        "error": "string",
        "file": {
          "data": "aGVsbG8=",
          "filename": "string",
          "mime": "string",
          "size": 0
        },
        "finished_at": 0,
        "format": "string",
        "ok": true,
        "skipped": true,
        "started_at": 0,
        "step_id": "string",
        "type": "string"
      }
    ],
    "stored": {},
    "workflow_id": "string"
  },
  "sequence": {
    "id": "string",
    "options": {
      "continue_on_error": true
    },
    "refs": [
      {
        "variables": {
          "key": "string"
        },
        "workflow_id": "string"
      }
    ]
  },
  "sequence_result": {
    "error": "string",
    "finished_at": 0,
    "ok": true,
    "sequence_id": "string",
    "started_at": 0,
    "workflows": [
      {
        "error": "string",
        "finished_at": 0,
        "ok": true,
        "started_at": 0,
        "steps": [
          {
            "data": null,
            "error": "string",
            "file": {
              "data": "aGVsbG8=",
              "filename": "string",
              "mime": "string",
              "size": 0
            },
            "finished_at": 0,
            "format": "string",
            "ok": true,
            "skipped": true,
            "started_at": 0,
            "step_id": "string",
            "type": "string"
          }
        ],
        "stored": {},
        "workflow_id": "string"
      }
    ]
  },
  "type": "string",
  "variables": {
    "key": "string"
  },
  "workflow": {
    "condition": {
      "match": "string",
      "negate": true,
      "selector": "string",
      "text": "string",
      "url_includes": "string"
    },
    "id": "string",
    "name": "string",
    "options": {
      "concurrency": "string",
      "continue_on_error": true,
      "default_timeout_ms": 0
    },
    "steps": [
      {
        "args": [
          null
        ],
        "attribute": "string",
        "body_params": {
          "key": "string"
        },
        "condition": {
          "match": "string",
          "negate": true,
          "selector": "string",
          "text": "string",
          "url_includes": "string"
        },
        "continue_on": {
          "manual": true,
          "selector": "string",
          "text": "string",
          "timeout_ms": 0,
          "url_includes": "string"
        },
        "filename": "string",
        "fn": "string",
        "format": "string",
        "id": "string",
        "label": "string",
        "optional": true,
        "output": "string",
        "prompt": "string",
        "selector": {
          "all": true,
          "css": "string",
          "index": 0,
          "indexes": [
            0
          ],
          "path": "string"
        },
        "store": "string",
        "timeout_ms": 0,
        "type": "string",
        "url": "string",
        "value": "string",
        "wait": {
          "absent": true,
          "delay_ms": 0,
          "selector": "string",
          "text": "string",
          "timeout_ms": 0,
          "url_includes": "string"
        }
      }
    ],
    "target": {
      "activate": true,
      "match_url": "string",
      "reload": true,
      "reuse_tab": true,
      "url": "string"
    }
  }
}
200 OK
{
  "key": "string"
}
POST/v1/extension/runAuth

Runs one inline workflow and replies with its terminal result

ext.DispatchHandler.Run

Body

application/jsonrequired
client_idstring

Names the target extension.

timeout_msinteger (int64)

Bounds the dispatch, in milliseconds.

variablesobject

Are per-run values overriding the extension's stored defaults.

*stringany additional property
workflowWorkflowrequired

Is one automation run the extension should perform against a page.

conditionCondition

Gates whether a workflow or step runs.

matchstring

Decides how the set predicates combine, "any" or "all".

negateboolean

Inverts the combined result.

selectorstring

Holds when a matching element exists on the page.

textstring

Holds when the page (or the selected element) contains this text.

url_includesstring

Holds when the page URL contains this substring.

idstring

Uniquely names the workflow.

namestring

Is the human-readable title shown in the extension UI.

optionsWorkflowOptions

Carries run-wide defaults for a workflow.

concurrencystring

Is the contention policy when another run already holds the target tab, one of "queue" (default), "parallel", or "reject".

continue_on_errorboolean

Keeps the run going past a failed step instead of stopping at the first failure.

default_timeout_msinteger (int64)

Is the per-step timeout in milliseconds for steps that do not set their own.

stepsStep[]

Are the actions to perform, in order.

argsunknown[]

Are the arguments passed to Fn.

attributestring

Names the DOM attribute an extraction step reads.

body_paramsobject

Overrides or adds form fields on the re-issued request of a captureDownload step.

*stringany additional property
conditionCondition

Gates whether a workflow or step runs.

matchstring

Decides how the set predicates combine, "any" or "all".

negateboolean

Inverts the combined result.

selectorstring

Holds when a matching element exists on the page.

textstring

Holds when the page (or the selected element) contains this text.

url_includesstring

Holds when the page URL contains this substring.

continue_onContinueCondition

Holds a step until a user gate is cleared or a page condition is met.

manualboolean

Pauses the run for an explicit user continue.

selectorstring

Resumes when a matching element appears.

textstring

Resumes when this text is present on the page.

timeout_msinteger (int64)

Bounds the hold, in milliseconds.

url_includesstring

Resumes when the page URL contains this substring.

filenamestring

Renames a captured file (captureDownload).

fnstring

Names the page function an eval step invokes.

formatstring

Names the shape extraction steps return their data in.

idstring

Uniquely names the step within its workflow, echoed on its StepResult.

labelstring

Is a human-readable description shown in run progress UIs.

optionalboolean

Lets the run continue when this step fails.

outputstring

Chooses where a captured file goes, the transport or disk.

promptstring

Is the text shown at a user gate asking for manual input.

selectorSelector

Picks the DOM node(s) a step acts on, by CSS or an explicit path, optionally narrowed to specific indexes or expanded to all matches.

allboolean

Expands the step to act on every match instead of the first.

cssstring

Is a CSS selector.

indexinteger (int64)

Narrows a multi-match selector to a single position.

indexesinteger (int64)[]

Narrows a multi-match selector to these positions.

pathstring

Is an explicit DOM path, used when CSS cannot express the target.

storestring

Names a slot the step's data is saved under, readable by later steps and returned on the WorkflowResult.

timeout_msinteger (int64)

Overrides the workflow's default step timeout, in milliseconds.

typestring

Is the action to perform (click, fill, select, captureDownload, ...).

urlstring

Is the address for navigation steps.

valuestring

Is the input for value-taking steps such as fill and select.

waitWaitConfig

Makes a step block until a page condition holds.

absentboolean

Flips the wait to expect the selector to disappear rather than appear.

delay_msinteger (int64)

Is a fixed pause in milliseconds, applied on top of any condition.

selectorstring

Waits for a matching element to appear (or disappear, see Absent).

textstring

Waits for this text to be present on the page.

timeout_msinteger (int64)

Bounds the wait, in milliseconds.

url_includesstring

Waits for the page URL to contain this substring.

targetTargetConfig

Locates the page a workflow runs against and controls how the tab hosting it is managed.

activateboolean

Brings the target tab to the foreground.

match_urlstring

Is a substring an existing tab's URL must contain for the run to reuse that tab instead of opening URL.

reloadboolean

Forces a page reload on a reused tab before the first step runs.

reuse_tabboolean

Reuses a matching open tab instead of opening a new one.

urlstring

Is the address to open when no existing tab matches.

Responses

200 OKOK
errorstring

Describes what stopped the run when OK is false.

finished_atinteger (int64)

Is when the run ended, in Unix milliseconds.

okboolean

Reports whether the run succeeded.

started_atinteger (int64)

Is when the run began, in Unix milliseconds.

stepsStepResult[]

Holds each step's result, in run order.

dataunknown

Is the step's extracted output, if any.

errorstring

Describes the failure when OK is false.

fileCapturedFile

Is a file a step produced, inlined in a StepResult.

datastring (byte)

Is the raw file content.

filenamestring

Is the file's name, after any step-level rename.

mimestring

Is the file's content type.

sizeinteger (int64)

Is the byte length of Data.

finished_atinteger (int64)

Is when the step ended, in Unix milliseconds.

formatstring

Names the shape Data is in.

okboolean

Reports whether the step succeeded.

skippedboolean

Is true when the step's condition was not met, so it neither ran nor failed.

started_atinteger (int64)

Is when the step began, in Unix milliseconds.

step_idstring

Is the id of the step this result belongs to.

typestring

Echoes the step's action type.

storedobject

Holds the values the workflow's store steps captured, keyed by store name, so a sequence chains one fragment's output into the next and a caller can read them.

workflow_idstring

Is the id of the workflow this result belongs to.

400 Bad Requestthe request could not be completed
errorstringrequired
403 Forbiddenthe request could not be completed
errorstringrequired
409 Conflictthe request could not be completed
errorstringrequired
500 Internal Server Errorthe request could not be completed
errorstringrequired
504 Gateway Timeoutthe request could not be completed
errorstringrequired
Defaultthe request could not be completed
errorstringrequired
Request body
{
  "client_id": "string",
  "timeout_ms": 0,
  "variables": {
    "key": "string"
  },
  "workflow": {
    "condition": {
      "match": "string",
      "negate": true,
      "selector": "string",
      "text": "string",
      "url_includes": "string"
    },
    "id": "string",
    "name": "string",
    "options": {
      "concurrency": "string",
      "continue_on_error": true,
      "default_timeout_ms": 0
    },
    "steps": [
      {
        "args": [
          null
        ],
        "attribute": "string",
        "body_params": {
          "key": "string"
        },
        "condition": {
          "match": "string",
          "negate": true,
          "selector": "string",
          "text": "string",
          "url_includes": "string"
        },
        "continue_on": {
          "manual": true,
          "selector": "string",
          "text": "string",
          "timeout_ms": 0,
          "url_includes": "string"
        },
        "filename": "string",
        "fn": "string",
        "format": "string",
        "id": "string",
        "label": "string",
        "optional": true,
        "output": "string",
        "prompt": "string",
        "selector": {
          "all": true,
          "css": "string",
          "index": 0,
          "indexes": [
            0
          ],
          "path": "string"
        },
        "store": "string",
        "timeout_ms": 0,
        "type": "string",
        "url": "string",
        "value": "string",
        "wait": {
          "absent": true,
          "delay_ms": 0,
          "selector": "string",
          "text": "string",
          "timeout_ms": 0,
          "url_includes": "string"
        }
      }
    ],
    "target": {
      "activate": true,
      "match_url": "string",
      "reload": true,
      "reuse_tab": true,
      "url": "string"
    }
  }
}
200 OK
{
  "error": "string",
  "finished_at": 0,
  "ok": true,
  "started_at": 0,
  "steps": [
    {
      "data": null,
      "error": "string",
      "file": {
        "data": "aGVsbG8=",
        "filename": "string",
        "mime": "string",
        "size": 0
      },
      "finished_at": 0,
      "format": "string",
      "ok": true,
      "skipped": true,
      "started_at": 0,
      "step_id": "string",
      "type": "string"
    }
  ],
  "stored": {},
  "workflow_id": "string"
}
POST/v1/extension/sequenceAuth

Runs an ordered list of library fragment references as one job and replies with the per-fragment results

ext.DispatchHandler.Sequence

Body

application/jsonrequired
client_idstring

Names the target extension.

optionsSequenceOptions

Tunes how a sequence handles a fragment failure.

continue_on_errorboolean

Keeps the sequence going after a fragment fails instead of stopping at the first failure.

refsSequenceRef[]

Are the library fragments to run, in order.

variablesobject

Apply to this fragment only, merged over the sequence-wide bag.

*stringany additional property
workflow_idstring

Is the id of the library fragment to run.

timeout_msinteger (int64)

Bounds the dispatch, in milliseconds.

variablesobject

Are sequence-wide values, overridable per ref.

*stringany additional property

Responses

200 OKOK
errorstring

Describes what stopped the sequence when OK is false.

finished_atinteger (int64)

Is when the sequence ended, in Unix milliseconds.

okboolean

Reports whether every fragment succeeded.

sequence_idstring

Is the id of the sequence these results belong to.

started_atinteger (int64)

Is when the sequence began, in Unix milliseconds.

workflowsWorkflowResult[]

Holds each fragment's result, in run order.

errorstring

Describes what stopped the run when OK is false.

finished_atinteger (int64)

Is when the run ended, in Unix milliseconds.

okboolean

Reports whether the run succeeded.

started_atinteger (int64)

Is when the run began, in Unix milliseconds.

stepsStepResult[]

Holds each step's result, in run order.

dataunknown

Is the step's extracted output, if any.

errorstring

Describes the failure when OK is false.

fileCapturedFile

Is a file a step produced, inlined in a StepResult.

datastring (byte)

Is the raw file content.

filenamestring

Is the file's name, after any step-level rename.

mimestring

Is the file's content type.

sizeinteger (int64)

Is the byte length of Data.

finished_atinteger (int64)

Is when the step ended, in Unix milliseconds.

formatstring

Names the shape Data is in.

okboolean

Reports whether the step succeeded.

skippedboolean

Is true when the step's condition was not met, so it neither ran nor failed.

started_atinteger (int64)

Is when the step began, in Unix milliseconds.

step_idstring

Is the id of the step this result belongs to.

typestring

Echoes the step's action type.

storedobject

Holds the values the workflow's store steps captured, keyed by store name, so a sequence chains one fragment's output into the next and a caller can read them.

workflow_idstring

Is the id of the workflow this result belongs to.

400 Bad Requestthe request could not be completed
errorstringrequired
403 Forbiddenthe request could not be completed
errorstringrequired
409 Conflictthe request could not be completed
errorstringrequired
500 Internal Server Errorthe request could not be completed
errorstringrequired
504 Gateway Timeoutthe request could not be completed
errorstringrequired
Defaultthe request could not be completed
errorstringrequired
Request body
{
  "client_id": "string",
  "options": {
    "continue_on_error": true
  },
  "refs": [
    {
      "variables": {
        "key": "string"
      },
      "workflow_id": "string"
    }
  ],
  "timeout_ms": 0,
  "variables": {
    "key": "string"
  }
}
200 OK
{
  "error": "string",
  "finished_at": 0,
  "ok": true,
  "sequence_id": "string",
  "started_at": 0,
  "workflows": [
    {
      "error": "string",
      "finished_at": 0,
      "ok": true,
      "started_at": 0,
      "steps": [
        {
          "data": null,
          "error": "string",
          "file": {
            "data": "aGVsbG8=",
            "filename": "string",
            "mime": "string",
            "size": 0
          },
          "finished_at": 0,
          "format": "string",
          "ok": true,
          "skipped": true,
          "started_at": 0,
          "step_id": "string",
          "type": "string"
        }
      ],
      "stored": {},
      "workflow_id": "string"
    }
  ]
}
POST/v1/extension/syncAuth

Pushes the fragment library to the extension and waits for its ack

ext.DispatchHandler.Sync

Body

application/jsonrequired
client_idstring

Names the target extension.

replaceboolean

Swaps the whole library instead of the default merge-by-id.

timeout_msinteger (int64)

Bounds the dispatch, in milliseconds.

workflowsWorkflow[]

Are the fragments to install in the extension's library.

conditionCondition

Gates whether a workflow or step runs.

matchstring

Decides how the set predicates combine, "any" or "all".

negateboolean

Inverts the combined result.

selectorstring

Holds when a matching element exists on the page.

textstring

Holds when the page (or the selected element) contains this text.

url_includesstring

Holds when the page URL contains this substring.

idstring

Uniquely names the workflow.

namestring

Is the human-readable title shown in the extension UI.

optionsWorkflowOptions

Carries run-wide defaults for a workflow.

concurrencystring

Is the contention policy when another run already holds the target tab, one of "queue" (default), "parallel", or "reject".

continue_on_errorboolean

Keeps the run going past a failed step instead of stopping at the first failure.

default_timeout_msinteger (int64)

Is the per-step timeout in milliseconds for steps that do not set their own.

stepsStep[]

Are the actions to perform, in order.

argsunknown[]

Are the arguments passed to Fn.

attributestring

Names the DOM attribute an extraction step reads.

body_paramsobject

Overrides or adds form fields on the re-issued request of a captureDownload step.

*stringany additional property
conditionCondition

Gates whether a workflow or step runs.

matchstring

Decides how the set predicates combine, "any" or "all".

negateboolean

Inverts the combined result.

selectorstring

Holds when a matching element exists on the page.

textstring

Holds when the page (or the selected element) contains this text.

url_includesstring

Holds when the page URL contains this substring.

continue_onContinueCondition

Holds a step until a user gate is cleared or a page condition is met.

manualboolean

Pauses the run for an explicit user continue.

selectorstring

Resumes when a matching element appears.

textstring

Resumes when this text is present on the page.

timeout_msinteger (int64)

Bounds the hold, in milliseconds.

url_includesstring

Resumes when the page URL contains this substring.

filenamestring

Renames a captured file (captureDownload).

fnstring

Names the page function an eval step invokes.

formatstring

Names the shape extraction steps return their data in.

idstring

Uniquely names the step within its workflow, echoed on its StepResult.

labelstring

Is a human-readable description shown in run progress UIs.

optionalboolean

Lets the run continue when this step fails.

outputstring

Chooses where a captured file goes, the transport or disk.

promptstring

Is the text shown at a user gate asking for manual input.

selectorSelector

Picks the DOM node(s) a step acts on, by CSS or an explicit path, optionally narrowed to specific indexes or expanded to all matches.

allboolean

Expands the step to act on every match instead of the first.

cssstring

Is a CSS selector.

indexinteger (int64)

Narrows a multi-match selector to a single position.

indexesinteger (int64)[]

Narrows a multi-match selector to these positions.

pathstring

Is an explicit DOM path, used when CSS cannot express the target.

storestring

Names a slot the step's data is saved under, readable by later steps and returned on the WorkflowResult.

timeout_msinteger (int64)

Overrides the workflow's default step timeout, in milliseconds.

typestring

Is the action to perform (click, fill, select, captureDownload, ...).

urlstring

Is the address for navigation steps.

valuestring

Is the input for value-taking steps such as fill and select.

waitWaitConfig

Makes a step block until a page condition holds.

absentboolean

Flips the wait to expect the selector to disappear rather than appear.

delay_msinteger (int64)

Is a fixed pause in milliseconds, applied on top of any condition.

selectorstring

Waits for a matching element to appear (or disappear, see Absent).

textstring

Waits for this text to be present on the page.

timeout_msinteger (int64)

Bounds the wait, in milliseconds.

url_includesstring

Waits for the page URL to contain this substring.

targetTargetConfig

Locates the page a workflow runs against and controls how the tab hosting it is managed.

activateboolean

Brings the target tab to the foreground.

match_urlstring

Is a substring an existing tab's URL must contain for the run to reuse that tab instead of opening URL.

reloadboolean

Forces a page reload on a reused tab before the first step runs.

reuse_tabboolean

Reuses a matching open tab instead of opening a new one.

urlstring

Is the address to open when no existing tab matches.

Responses

200 OKOK
*stringany additional property
400 Bad Requestthe request could not be completed
errorstringrequired
403 Forbiddenthe request could not be completed
errorstringrequired
409 Conflictthe request could not be completed
errorstringrequired
500 Internal Server Errorthe request could not be completed
errorstringrequired
504 Gateway Timeoutthe request could not be completed
errorstringrequired
Defaultthe request could not be completed
errorstringrequired
Request body
{
  "client_id": "string",
  "replace": true,
  "timeout_ms": 0,
  "workflows": [
    {
      "condition": {
        "match": "string",
        "negate": true,
        "selector": "string",
        "text": "string",
        "url_includes": "string"
      },
      "id": "string",
      "name": "string",
      "options": {
        "concurrency": "string",
        "continue_on_error": true,
        "default_timeout_ms": 0
      },
      "steps": [
        {
          "args": [
            null
          ],
          "attribute": "string",
          "body_params": {
            "key": "string"
          },
          "condition": {
            "match": "string",
            "negate": true,
            "selector": "string",
            "text": "string",
            "url_includes": "string"
          },
          "continue_on": {
            "manual": true,
            "selector": "string",
            "text": "string",
            "timeout_ms": 0,
            "url_includes": "string"
          },
          "filename": "string",
          "fn": "string",
          "format": "string",
          "id": "string",
          "label": "string",
          "optional": true,
          "output": "string",
          "prompt": "string",
          "selector": {
            "all": true,
            "css": "string",
            "index": 0,
            "indexes": [
              0
            ],
            "path": "string"
          },
          "store": "string",
          "timeout_ms": 0,
          "type": "string",
          "url": "string",
          "value": "string",
          "wait": {
            "absent": true,
            "delay_ms": 0,
            "selector": "string",
            "text": "string",
            "timeout_ms": 0,
            "url_includes": "string"
          }
        }
      ],
      "target": {
        "activate": true,
        "match_url": "string",
        "reload": true,
        "reuse_tab": true,
        "url": "string"
      }
    }
  ]
}
200 OK
{
  "key": "string"
}

Frontend

POST/v1/frontend/newsletter/subscribePublic

Records a newsletter signup

It rejects a missing or malformed email, silently accepts honeypot-tripping bot submissions without storing them, upserts the address, and fires a best-effort Slack notification.

web.Handler.Subscribe

Body

application/jsonrequired
emailstringrequired
namestringrequired

Responses

200 OKOK
messagestringrequired
400 Bad Requestthe request could not be completed
errorstringrequired
500 Internal Server Errorthe request could not be completed
errorstringrequired
Defaultthe request could not be completed
errorstringrequired
Request body
{
  "email": "string",
  "name": "string"
}
200 OK
{
  "message": "string"
}