Agents API

These endpoints help AI agents discover and understand your Broadcast instance. They complement the existing API endpoints for subscribers, broadcasts, sequences, and more.

All endpoints require a valid API token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Whoami

Returns information about the current API token, including its type, permissions, and associated channel.

GET /api/v1/whoami

Response

{
  "token": {
    "label": "My API Token",
    "type": "channel_scoped",
    "redacted_value": "8779••••••••c8b9",
    "last_used_at": "2026-02-20T10:30:00Z",
    "permissions": {
      "subscribers_read": true,
      "subscribers_write": true,
      "broadcasts_read": true,
      "broadcasts_write": false,
      "sequences_read": true,
      "sequences_write": false,
      "templates_read": false,
      "templates_write": false,
      "segments_read": true,
      "segments_write": false,
      "email_servers_read": false,
      "email_servers_write": false,
      "opt_in_forms_read": false,
      "opt_in_forms_write": false,
      "transactionals_read": false,
      "transactionals_write": false,
      "webhook_endpoints_read": false,
      "webhook_endpoints_write": false
    }
  },
  "channel": {
    "id": 1,
    "name": "Main Broadcast Channel",
    "slug": "main-channel"
  }
}

For admin (cross-channel) tokens, the type field returns "admin_cross_channel" and the channel section reflects the channel specified by broadcast_channel_id.

Status

Returns the health and readiness of the current broadcast channel.

GET /api/v1/status

Response

{
  "channel": {
    "name": "Main Broadcast Channel",
    "sender_email": "[email protected]",
    "sender_name": "Example Broadcaster"
  },
  "subscribers": {
    "total": 5000,
    "active": 4800
  },
  "readiness": {
    "broadcasts": true,
    "sequences": true,
    "transactionals": true
  }
}

The readiness section indicates whether the channel has the necessary configuration (email servers, sender details, etc.) to send each type of email.

Prime

Returns a comprehensive capabilities manifest — the single endpoint an agent needs to understand everything it can do.

GET /api/v1/prime

Response

{
  "platform": {
    "name": "Broadcast",
    "version": "2.0.0",
    "host": "https://your-instance.com"
  },
  "authentication": {
    "token_type": "channel_scoped",
    "permissions": {
      "subscribers_read": true,
      "subscribers_write": true,
      "broadcasts_read": true,
      "broadcasts_write": false
    }
  },
  "channel_status": {
    "name": "Main Broadcast Channel",
    "subscribers_count": 5000,
    "broadcasts_ready": true,
    "sequences_ready": true,
    "transactionals_ready": true
  },
  "capabilities": [
    {
      "resource": "subscribers",
      "description": "Manage email list contacts",
      "endpoints": [
        { "method": "GET", "path": "/api/v1/subscribers", "description": "List subscribers" },
        { "method": "GET", "path": "/api/v1/subscribers/find?email=X", "description": "Find subscriber by email" },
        { "method": "POST", "path": "/api/v1/subscribers", "description": "Create subscriber" },
        { "method": "PATCH", "path": "/api/v1/subscribers", "description": "Update subscriber" },
        { "method": "POST", "path": "/api/v1/subscribers/add_tag", "description": "Add tag" },
        { "method": "DELETE", "path": "/api/v1/subscribers/remove_tag", "description": "Remove tag" }
      ]
    },
    {
      "resource": "broadcasts",
      "description": "Email campaigns",
      "endpoints": [
        { "method": "GET", "path": "/api/v1/broadcasts", "description": "List broadcasts" },
        { "method": "GET", "path": "/api/v1/broadcasts/:id", "description": "Get broadcast" }
      ]
    }
  ],
  "rate_limit": {
    "requests_per_minute": 120
  },
  "tips": [
    "Use GET /api/v1/subscribers/find?email=X to look up a subscriber before creating a duplicate.",
    "Always check broadcast status before sending — only 'draft' broadcasts can be sent.",
    "Use tags to organize subscribers and segments to target broadcasts."
  ]
}

Skill

Returns a detailed reference document that teaches agents how to use Broadcast effectively.

Public Skill (generic)

GET /agents/skill

Returns a generic skill file covering all CLI commands, common workflows, safety rules, and error handling. No authentication required.

Personalized Skill (authenticated)

GET /api/v1/skill

Returns the same content but personalized with your channel name, subscriber count, available permissions, and instance URL. Requires authentication.

Response

The response is a plain-text Markdown document:

Content-Type: text/plain

---
name: broadcast
description: Email marketing platform - manage subscribers, broadcasts, sequences
---

# Broadcast Email Marketing Skill

## Authentication
Your token has access to: subscribers (read/write), broadcasts (read)...

## Common Workflows
### Send a newsletter
1. broadcast broadcasts create --subject="Weekly Update" --body="..."
2. broadcast broadcasts send ID
...