Labels

Reply labels and the triggers they run. 6 endpoints, each also a tool for your AI through MCP. Authentication and errors are on the overview.

Labels with their triggers and lead counts

GET/api/v1/labels

MCP tool list_labelsRead-only

Returns

labelsrequiredobject[]

cURL

curl https://ballast.to/api/v1/labels \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Create a label

POST/api/v1/labels

MCP tool create_labelOwners and admins

Parameters

namerequiredstring
descriptionstring | null
aiPromptstring | null: Tells the reply classifier when to apply it. Empty = applied by hand only.
typerequired"positive" | "negative" | "neutral" | "warning"
triggersrequiredobject

Returns

idrequiredstring
namerequiredstring
descriptionrequiredstring | null
aiPromptrequiredstring | null
typerequired"positive" | "negative" | "neutral" | "warning"
triggersrequiredobject
positionrequirednumber
systemrequiredboolean: Used by the engine: editable, not deletable
leadsrequirednumber

cURL

curl -X POST https://ballast.to/api/v1/labels \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","type":"positive","triggers":{}}'

Change a label, its AI prompt or triggers

PATCH/api/v1/labels/{id}

MCP tool update_labelOwners and admins

Parameters

idrequiredpath · string
namerequiredstring
descriptionstring | null
aiPromptstring | null: Tells the reply classifier when to apply it. Empty = applied by hand only.
typerequired"positive" | "negative" | "neutral" | "warning"
triggersrequiredobject

Returns the same fields as Create a label.

cURL

curl -X PATCH https://ballast.to/api/v1/labels/<id> \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","type":"positive","triggers":{}}'

Delete a label

DELETE/api/v1/labels/{id}

Removes it from every lead. Labels the engine relies on can't be deleted.

MCP tool delete_labelOwners and adminsMCP asks to confirm

Parameters

idrequiredpath · string

Returns

okrequiredtrue

cURL

curl -X DELETE https://ballast.to/api/v1/labels/<id> \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Set the label order

POST/api/v1/labels/reorder

Owners and admins

Parameters

idsrequiredstring[]

Returns

okrequiredtrue

cURL

curl -X POST https://ballast.to/api/v1/labels/reorder \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":[]}'

Run the reply classifier on a sample reply

POST/api/v1/labels/test

Uses every label's AI prompt, with `draft` replacing one label's saved prompt, so a prompt can be tried before saving. Nothing is labeled.

MCP tool test_label_promptNeeds an active plan

Parameters

subjectstring | null
replyrequiredstring
draftobject | null

Returns

labelIdrequiredstring | null: Null: no label fits well enough, a human decides. "draft" when the unsaved new label wins
labelNamerequiredstring | null
confidencerequirednumber
reasonrequiredstring
sourcerequiredstring: "rules" for auto-replies caught without a model, else the model id

cURL

curl -X POST https://ballast.to/api/v1/labels/test \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reply":"<reply>"}'

Create a label

POST/api/v1/labels

MCP tool create_labelOwners and admins

Parameters

namerequiredstring
descriptionstring | null
aiPromptstring | null: Tells the reply classifier when to apply it. Empty = applied by hand only.
typerequired"positive" | "negative" | "neutral" | "warning"
triggersrequiredobject

Returns

idrequiredstring
namerequiredstring
descriptionrequiredstring | null
aiPromptrequiredstring | null
typerequired"positive" | "negative" | "neutral" | "warning"
triggersrequiredobject
positionrequirednumber
systemrequiredboolean: Used by the engine: editable, not deletable
leadsrequirednumber

Change a label, its AI prompt or triggers

PATCH/api/v1/labels/{id}

MCP tool update_labelOwners and admins

Parameters

idrequiredpath · string
namerequiredstring
descriptionstring | null
aiPromptstring | null: Tells the reply classifier when to apply it. Empty = applied by hand only.
typerequired"positive" | "negative" | "neutral" | "warning"
triggersrequiredobject

Returns the same fields as Create a label.

Run the reply classifier on a sample reply

POST/api/v1/labels/test

Uses every label's AI prompt, with `draft` replacing one label's saved prompt, so a prompt can be tried before saving. Nothing is labeled.

MCP tool test_label_promptNeeds an active plan

Parameters

subjectstring | null
replyrequiredstring
draftobject | null

Returns

labelIdrequiredstring | null: Null: no label fits well enough, a human decides. "draft" when the unsaved new label wins
labelNamerequiredstring | null
confidencerequirednumber
reasonrequiredstring
sourcerequiredstring: "rules" for auto-replies caught without a model, else the model id