Skip to main content

Concepts

Commands and receipts

Every write carries your own command_id, so retries are safe and a lost reply can always be reconciled.

View as Markdown

Every operation that changes something is a command. You generate a UUID, send it as command_id, and Browlix applies the command at most once.

Retrying safely

  • The first time, the reply is 201 with replayed: false.
  • Sending the same command_id with the same body again returns the stored result with 200 and replayed: true. Nothing is applied twice.
  • Sending the same command_id with a different body is CONFLICT: one id names one intent.

So when a request times out or the connection drops, resend it with the same id. Never generate a new id for a retry — that would be a second command.

After a lost reply

If you are not sure a command was received, ask for its receipt instead of writing again:

bash
curl https://browlix.com/api/public/v1/receipts/$COMMAND_ID \
  -H "Authorization: Bearer $BROWLIX_API_KEY"

NOT_FOUND means the command never arrived, so sending it is safe. A receipt tells you how it ended.

OUTCOME_UNKNOWN

Some effects happen outside Browlix — a page submitting a form, a webhook to your server. When a step's effect cannot be confirmed, Browlix says so with OUTCOME_UNKNOWN (HTTP 202) instead of guessing, and automation never repeats such a step on its own. Decide with run_targets.resolve (happened / not_happened) or look at the target system.

In the SDK, CLI and MCP

  • The SDK generates a command_id when you omit one and returns it as reply.commandId; its automatic retries reuse it.
  • The CLI prints the id it used; pass --command-id to retry with the same one.
  • MCP tools generate one when the agent omits it and return it in the result; after a disconnect the agent calls receipts_get with it.