Skip to main content
POST
Create Goal Bot
Goal bots and task agents are the same object. The two engines merged; /api/goal-bots and /api/tasks are aliases over one collection and return identical bodies. Every response carries both goalBot and taskAgent (or goalBots and taskAgents) so integrations written against either name keep working.The older stage-based engine moved to /api/instructions and is being retired.
A goal bot is one prompt plus the tags that wake it. There are no stages — tag a lead and the bot handles their replies.
A new bot is live the moment it is created and will start answering leads whose tags already match. Pass "status": "paused" if you want to create it, read it back, and switch it on deliberately.

Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

Request body

string
required
Display name for the bot. An empty or missing name returns 400 Name is required.
string
required
The instructions the model runs on — who it is, what it is trying to do, what it must not say. An empty or missing prompt returns 400 Prompt is required.
string[]
Tags that wake this bot. A lead carrying any of them is handled by this bot when it replies. Set tags with PATCH /api/leads/{id}. Defaults to [].
string[]
Tags that keep a lead away from this bot, even when includeTags matches. Defaults to [].
string
default:"autopilot"
How replies are delivered.
An unrecognised value is not rejected — it is silently stored as copilot. Read the mode back from the response to confirm what was saved.
string
default:"active"
active or paused. A new bot goes live the moment it exists and starts answering leads whose tags already match, so pass "paused" when you want to create, inspect, then flip it on with PATCH. Any value other than "paused" is stored as active.
string
default:"calendly"
Calendar used for booking: calendly or ghl_calendar. Any other value falls back to calendly.
string
default:"always"
When the bot searches your knowledge base. always searches on every inbound message; auto leaves the decision to the model. On create, anything other than "auto" is stored as always.
string
Free-text tone hint, e.g. "warm and brief".
boolean
default:"true"
Whether the bot may ask the lead follow-up questions. Only an explicit false turns it off.
boolean
default:"true"
Send a typing signal before replying. Only an explicit false turns it off.
number
default:"8"
How many times the bot may reply in one conversation. Clamped to 1–20; a non-numeric or non-positive value falls back to 8.
string
Tag applied to the lead when the bot reaches its goal.
boolean
default:"false"
Push onDoneTag to the connected CRM as well as to Tuco. Only an explicit true enables it.
string[]
Ids of the API tools this bot may call, from GET /api/campaign-tools. Omit to allow none.
string[]
Field names the bot should try to collect during the conversation, e.g. ["email", "company"].

Example

Success (200 OK)

The response is 200, not 201. Read goalBot._id and use it on every {id} route.

Errors