Campaigns API
CRUD and lifecycle endpoints for managing campaigns programmatically.
All campaign endpoints live under /api/v1/campaigns. They require a Sanctum bearer token (see Authentication) with the campaigns:read, campaigns:write, or campaigns:control ability depending on the verb.
List campaigns
GET /api/v1/campaigns — returns a paginated list of campaigns owned by the authenticated user.
curl https://prime-bot.live/api/v1/campaigns \
-H "Authorization: Bearer $TOKEN"{
"data": [
{
"id": 1,
"name": "Pricing replies",
"mode": "auto_reply",
"trigger_keyword": "pricing",
"status": "running",
"telegram_account_id": 3,
"scheduled_at": null,
"started_at": "2026-04-18T09:14:02Z",
"completed_at": null,
"total_contacts": 0,
"sent_count": 87,
"failed_count": 1
}
],
"meta": {
"pagination": {
"current_page": 1,
"per_page": 25,
"total": 1,
"last_page": 1
}
}
}Create a campaign
POST /api/v1/campaigns — requires campaigns:write.
curl -X POST https://prime-bot.live/api/v1/campaigns \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Support triage",
"mode": "auto_reply",
"trigger_keyword": "help",
"telegram_account_id": 3,
"body": "Hey! A human will follow up within one business hour."
}'Returns 201 Created with the new campaign inside data.
Fetch one
GET /api/v1/campaigns/{id} — returns a single campaign envelope.
curl https://prime-bot.live/api/v1/campaigns/1 \
-H "Authorization: Bearer $TOKEN"Update
PUT /api/v1/campaigns/{id} — same payload shape as create; only the supplied fields are updated.
curl -X PUT https://prime-bot.live/api/v1/campaigns/1 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"trigger_keyword": "price"}'Delete
DELETE /api/v1/campaigns/{id} — soft-deletes the campaign. In-flight sends complete, then the campaign disappears from subsequent list calls.
curl -X DELETE https://prime-bot.live/api/v1/campaigns/1 \
-H "Authorization: Bearer $TOKEN"Lifecycle controls
These three endpoints require campaigns:control. They are idempotent — calling start on a running campaign is a no-op that still returns 200.
| Method | Path | Does |
|---|---|---|
| POST | /campaigns/{id}/start | Transitions to running and begins consuming triggers or draining the broadcast queue. |
| POST | /campaigns/{id}/pause | Transitions to paused. Queued sends halt; inbound events queue up for when you resume. |
| POST | /campaigns/{id}/stop | Terminal stopped. Queued sends are discarded and the campaign cannot be restarted. |
curl -X POST https://prime-bot.live/api/v1/campaigns/1/pause \
-H "Authorization: Bearer $TOKEN"Related resources
- Senders — list contacts/senders scoped to a campaign.
- Logs — inspect every message the campaign has sent.
- OpenAPI spec — machine-readable version of this reference.