API docs by Redocly

Passband API (1.0.0)

Download OpenAPI specification:

REST API for accessing Passband drafts, triggering pipelines, and managing content programmatically.

List drafts

Returns a paginated list of drafts for the authenticated user.

Authorizations:
bearerAuth
query Parameters
status
string

Filter by status (e.g., pending_review, approved)

format
string

Filter by format (e.g., SHORT, THREAD, BLOG)

limit
integer [ 1 .. 100 ]
Default: 25

Number of items per page

cursor
string

Cursor for pagination (use nextCursor from previous response)

sourceId
string

Filter by source ID

sourceType
string

Filter by source type (e.g., rss, twitter)

tags
string

Filter by tags (comma-separated)

scheduledAfter
string <date-time>

Filter drafts scheduled after this timestamp

scheduledBefore
string <date-time>

Filter drafts scheduled before this timestamp

Responses

Response samples

Content type
application/json
{
  • "drafts": [
    ],
  • "nextCursor": "string"
}

Create draft

Creates one or more drafts. Supports two modes:

Direct mode — provide text (and optional format) to create a single draft with your own content. Great for one-off posts with image attachments.

Generate mode — provide url and/or prompt to have AI generate drafts in the specified formats using your voice profile.

Authorizations:
bearerAuth
Request Body schema: application/json
required
text
string [ 1 .. 50000 ] characters

Draft content (direct mode). Mutually exclusive with url/prompt.

format
string
Enum: "SHORT" "THREAD" "BLOG"

Draft format (direct mode). Defaults to SHORT.

url
string <uri>

Source URL for AI generation (generate mode).

prompt
string [ 1 .. 5000 ] characters

Prompt for AI generation (generate mode). Can be combined with url.

formats
Array of strings [ 1 .. 3 ] items
Items Enum: "SHORT" "THREAD" "BLOG"

Formats to generate (generate mode). Defaults to ["SHORT"].

Array of objects (CreateDraftImage) <= 10 items

Image attachments. In generate mode, images attach to the first draft.

tags
Array of strings <= 20 items [ items <= 50 characters ]

Tags for the created draft(s).

targetPlatforms
Array of strings

Target publishing platforms.

Responses

Request samples

Content type
application/json
Example
{
  • "text": "Check out our new feature launch!",
  • "format": "SHORT",
  • "images": [],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "mode": "direct",
  • "itemId": "string",
  • "drafts": [
    ]
}

Get draft by ID

Returns a single draft with full detail including source item information.

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "text": "string",
  • "format": "SHORT",
  • "status": "pending_generation",
  • "confidence": 0,
  • "feedback": "string",
  • "rejectionFeedback": "string",
  • "scheduledAt": "2019-08-24T14:15:22Z",
  • "postedAt": "2019-08-24T14:15:22Z",
  • "postId": "string",
  • "itemId": "string",
  • "regeneratedFromId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "item": {
    }
}

Update draft

Perform state transitions or edit a draft. Supported actions: approve, reject, regenerate, schedule, archive, unapprove, reschedule, cancel_schedule, post. Or send "text" to edit content.

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
action
string
Enum: "approve" "reject" "regenerate" "schedule" "archive" "unapprove" "reschedule" "cancel_schedule" "post"

State transition action

text
string

New text content for the draft

feedback
string

Feedback when rejecting or unapproving

scheduledAt
string <date-time>

ISO 8601 timestamp. Required for reschedule, optional for schedule.

smartSchedule
boolean

If true, use smart scheduling to find the next available slot. Used with action="schedule".

platforms
Array of strings

Target platforms for action="post". If omitted, posts to all connected platforms.

Responses

Request samples

Content type
application/json
{
  • "action": "approve",
  • "text": "string",
  • "feedback": "string",
  • "scheduledAt": "2019-08-24T14:15:22Z",
  • "smartSchedule": true,
  • "platforms": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "text": "string",
  • "format": "SHORT",
  • "status": "pending_generation",
  • "confidence": 0,
  • "feedback": "string",
  • "rejectionFeedback": "string",
  • "scheduledAt": "2019-08-24T14:15:22Z",
  • "postedAt": "2019-08-24T14:15:22Z",
  • "postId": "string",
  • "itemId": "string",
  • "regeneratedFromId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Trigger pipeline run

Queues a new pipeline run to ingest sources and generate drafts. The run executes asynchronously; poll /pipeline/runs to track progress.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "queued",
  • "message": "string"
}

List pipeline runs

Returns a paginated list of pipeline runs, most recent first.

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Number of runs per page

cursor
string

Cursor for pagination (use nextCursor from previous response)

Responses

Response samples

Content type
application/json
{
  • "runs": [
    ],
  • "nextCursor": "string"
}

Pipeline statistics

Returns aggregate pipeline run statistics for the authenticated user.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "totalRuns": 0,
  • "successRate": 0,
  • "averageDuration": 0,
  • "averageItemsPerRun": 0,
  • "averageDraftsPerRun": 0,
  • "topErrors": [
    ],
  • "last30Days": {
    }
}

Get voice profile

Returns the authenticated user's voice profile.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "style": "string",
  • "avoid": [
    ],
  • "examples": [
    ],
  • "formats": { },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update voice profile

Updates (or creates) the voice profile for the authenticated user.

Authorizations:
bearerAuth
Request Body schema: application/json
required
style
string
avoid
Array of strings
examples
Array of strings
formats
object

Responses

Request samples

Content type
application/json
{
  • "style": "string",
  • "avoid": [
    ],
  • "examples": [
    ],
  • "formats": { }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "style": "string",
  • "avoid": [
    ],
  • "examples": [
    ],
  • "formats": { },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Engagement summary

Returns aggregate engagement metrics and top posts.

Authorizations:
bearerAuth
query Parameters
top
integer [ 1 .. 50 ]
Default: 10

Number of top posts to return

Responses

Response samples

Content type
application/json
{
  • "totalPosted": 0,
  • "totalWithMetrics": 0,
  • "avgEngagementRate": 0,
  • "totalLikes": 0,
  • "totalReplies": 0,
  • "totalReposts": 0,
  • "totalImpressions": 0,
  • "topPosts": [
    ],
  • "byFormat": [
    ],
  • "byPlatform": [
    ]
}

Upsert engagement metrics

Records or updates engagement metrics for a draft on a platform.

Authorizations:
bearerAuth
Request Body schema: application/json
required
draftId
required
string non-empty
platform
required
string non-empty
postId
string
status
string
Enum: "pending" "posted" "failed" "abandoned"
errorMessage
string
likes
integer >= 0
replies
integer >= 0
reposts
integer >= 0
impressions
integer >= 0
clicks
integer >= 0

Responses

Request samples

Content type
application/json
{
  • "draftId": "string",
  • "platform": "string",
  • "postId": "string",
  • "status": "pending",
  • "errorMessage": "string",
  • "likes": 0,
  • "replies": 0,
  • "reposts": 0,
  • "impressions": 0,
  • "clicks": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "draftId": "string",
  • "platform": "string",
  • "postId": "string",
  • "status": "pending",
  • "retryCount": 0,
  • "retryAfter": "2019-08-24T14:15:22Z",
  • "errorMessage": "string",
  • "failedAt": "2019-08-24T14:15:22Z",
  • "likes": 0,
  • "replies": 0,
  • "reposts": 0,
  • "impressions": 0,
  • "clicks": 0,
  • "engagementRate": 0,
  • "measuredAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z"
}

List experiments

Returns A/B experiments for the authenticated user.

Authorizations:
bearerAuth
query Parameters
status
string
Enum: "active" "concluded" "archived"

Filter by experiment status

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create experiment

Creates a new A/B experiment.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters
parameter
required
string
required
Array of objects (ExperimentVariant) [ 2 .. 5 ] items

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "parameter": "string",
  • "variants": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "parameter": "string",
  • "status": "active",
  • "variants": [
    ],
  • "results": { },
  • "startedAt": "2019-08-24T14:15:22Z",
  • "endedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z"
}

List sources

Returns all sources for the authenticated user.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create source

Creates a new source and performs a test fetch to validate it.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
type
required
string
Enum: "rss" "twitter" "reddit" "hackernews" "google_news" "substack"
url
required
string <uri>
config
object

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "rss",
  • "name": "string",
  • "url": "string",
  • "config": { },
  • "enabled": true,
  • "lastFetch": "2019-08-24T14:15:22Z",
  • "health": "healthy",
  • "failCount": 0,
  • "lastError": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "itemCount": 0
}

Update source

Updates source configuration, name, or enabled status.

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
name
string [ 1 .. 200 ] characters
type
string
Enum: "rss" "twitter" "reddit" "hackernews" "google_news" "substack"
url
string <uri>
enabled
boolean
config
object

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "rss",
  • "name": "string",
  • "url": "string",
  • "config": { },
  • "enabled": true,
  • "lastFetch": "2019-08-24T14:15:22Z",
  • "health": "healthy",
  • "failCount": 0,
  • "lastError": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "itemCount": 0
}

Delete source

Deletes a source and all associated items and drafts.

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Test source

Performs a test fetch to validate source configuration.

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "items": [
    ],
  • "error": "string"
}

Bulk draft action

Perform an action on multiple drafts at once. Supports: approve, reject, archive, schedule, reschedule, cancel_schedule.

Authorizations:
bearerAuth
Request Body schema: application/json
required
action
required
string
Enum: "approve" "reject" "archive" "schedule" "reschedule" "cancel_schedule"
ids
required
Array of strings [ 1 .. 100 ] items
feedback
string

Feedback for reject action

scheduledAt
string <date-time>

Required for reschedule, optional for schedule

smartSchedule
boolean

Responses

Request samples

Content type
application/json
{
  • "action": "approve",
  • "ids": [
    ],
  • "feedback": "string",
  • "scheduledAt": "2019-08-24T14:15:22Z",
  • "smartSchedule": true
}

Response samples

Content type
application/json
{
  • "action": "string",
  • "total": 0,
  • "succeeded": 0,
  • "failed": 0,
  • "results": {
    }
}

Get schedule slots

Returns configured posting schedule slots.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "slots": [
    ]
}

Update schedule slots

Replace all schedule slots with a new configuration.

Authorizations:
bearerAuth
Request Body schema: application/json
required
Array
dayOfWeek
required
integer [ 0 .. 6 ]
hour
required
integer [ 0 .. 23 ]
minute
required
integer [ 0 .. 59 ]

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Add draft to schedule queue

Schedules an approved draft to the next available slot.

Authorizations:
bearerAuth
Request Body schema: application/json
required
draftId
required
string

Responses

Request samples

Content type
application/json
{
  • "draftId": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "text": "string",
  • "format": "SHORT",
  • "status": "pending_generation",
  • "confidence": 0,
  • "feedback": "string",
  • "rejectionFeedback": "string",
  • "scheduledAt": "2019-08-24T14:15:22Z",
  • "postedAt": "2019-08-24T14:15:22Z",
  • "postId": "string",
  • "itemId": "string",
  • "regeneratedFromId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List unscheduled drafts

Returns approved drafts that are not yet scheduled.

Authorizations:
bearerAuth

Responses

Check scheduling conflicts

Returns drafts scheduled within +/-30 minutes of the given time.

Authorizations:
bearerAuth
query Parameters
scheduledAt
required
string <date-time>
excludeDraftId
string

Responses

Response samples

Content type
application/json
{
  • "hasConflict": true,
  • "count": 0,
  • "conflicts": [
    ]
}

Get AI-recommended posting times

Returns optimal posting times based on engagement history. Results are cached.

Authorizations:
bearerAuth
query Parameters
platforms
required
string

Comma-separated platform names

Responses

Bulk schedule drafts

Automatically schedule multiple approved drafts to available slots.

Authorizations:
bearerAuth
Request Body schema: application/json
draftIds
Array of strings

Optional IDs to schedule. If omitted, schedules all approved.

Responses

Request samples

Content type
application/json
{
  • "draftIds": [
    ]
}

Response samples

Content type
application/json
{
  • "scheduled": [
    ],
  • "skipped": 0,
  • "reason": "string"
}

Get scheduling pause status

Returns whether scheduling is currently paused.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "paused": true
}

Toggle scheduling pause

Pause or resume the scheduling queue.

Authorizations:
bearerAuth
Request Body schema: application/json
required
paused
required
boolean

Responses

Request samples

Content type
application/json
{
  • "paused": true
}

Response samples

Content type
application/json
{
  • "paused": true
}

Get historical best posting times

Analyzes past engagement data to suggest best times to post.

Authorizations:
bearerAuth
query Parameters
platform
string

Filter by platform

Responses

Get calendar feed URL

Returns the iCal feed URL for scheduled posts.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "url": "string"
}