Workflows | BrokerBot

Workflows are the guided tasks your team sets up in BrokerBot, such as “Schedule a showing” or “Write a listing description”. Each one has a starter prompt, optional instructions for the agent, and an optional !command that starts it from chat. All endpoints use a team API key and are served under https://api.brokerbot.ai/v1/workflows. Deleted workflows are never returned.

Choosing a team

GET /v1/workflows takes an optional teamId query parameter: your top-level team (the default) or one of its sub-teams, by ID. A team or workflow outside your key’s tree returns 404:

{ "error": "Workflow not found" }

Workflow object

Field	Type	Description
`id`	string	Workflow ID.
`teamId`	string	Team that owns the workflow.
`agentId`	string	Assistant the workflow runs on.
`name`	string
`command`	string \| null	Chat command without the leading `!`, for example `schedule` for `!schedule`.
`description`	string \| null
`icon`	string \| null	Lucide icon name or emoji.
`iconColor`	string \| null	Hex color for the icon background.
`starterPrompt`	string \| null	Message sent to the agent when a user starts the workflow.
`visibility`	string	Who can run it: `private`, `team`, `shared`, `group`, or `individual`.
`enabled`	boolean	Disabled workflows can’t be started.
`isBuiltIn`	boolean	`true` for workflows BrokerBot provides.
`sortOrder`	integer	Display order, lowest first.
`createdAt`	string	ISO 8601 creation time.
`updatedAt`	string	ISO 8601 last update time.

List workflows

GET /v1/workflows

Lists a team’s workflows in display order. Workflows that belong to its sub-teams aren’t included; pass the sub-team’s teamId to list them.

Query parameter	Type	Description
`teamId`	string	Optional. Team to list. Defaults to the API key’s team.
`enabled`	string	Optional. `true` or `false`.
`page`	integer	Optional. Page number from 1. Default `1`.
`pageSize`	integer	Optional. 1–100. Default `20`.

curl "https://api.brokerbot.ai/v1/workflows?enabled=true" \
  -H "Authorization: Bearer $BROKERBOT_API_KEY"

{
  "workflows": [
    {
      "id": "6f1c1a52-8a0e-4c1e-9d0b-2d4f6f3b9a10",
      "teamId": "team_123",
      "agentId": "agent_789",
      "name": "Schedule a showing",
      "command": "schedule",
      "description": "Book a showing with the listing agent.",
      "icon": "calendar",
      "iconColor": "#2563eb",
      "starterPrompt": "Help me schedule a showing.",
      "visibility": "team",
      "enabled": true,
      "isBuiltIn": false,
      "sortOrder": 0,
      "createdAt": "2026-09-01T15:00:00.000Z",
      "updatedAt": "2026-09-20T09:30:00.000Z"
    }
  ],
  "pagination": {
    "totalCount": 1,
    "totalPages": 1,
    "currentPage": 1,
    "pageSize": 20
  }
}

Get a workflow

GET /v1/workflows/{workflowId}

Returns { "workflow": <Workflow object> } plus one more field:

Field	Type	Description
`instructions`	string \| null	Instructions the agent follows while running the workflow.

Errors

Status	When
`400`	Invalid query parameter.
`401`	Missing or invalid API key.
`404`	Team or workflow not found in your key’s tree.

See Errors for the error format.