Developer API Reference

Returns a paginated list of drafts for the account. Defaults to draft and scheduled status.

Query parameters

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/drafts"

# Filter by status
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/drafts?status=scheduled"

Response:

{
  "drafts": [
    {
      "id": 123,
      "status": "draft",
      "content": "Big news: we just shipped X...",
      "platforms": ["linkedin", "twitter"],
      "scheduled_at": null,
      "published_at": null,
      "created_at": "2026-03-01T09:00:00Z",
      "updated_at": "2026-03-01T09:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "items": 20,
    "count": 42,
    "pages": 3
  }
}

Retrieve a single draft by its ID.

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/drafts/123"

Response:

{
  "draft": {
    "id": 123,
    "status": "draft",
    "content": "Big news: we just shipped X...",
    "platforms": ["linkedin", "twitter"],
    "scheduled_at": null,
    "published_at": null,
    "created_at": "2026-03-01T09:00:00Z",
    "updated_at": "2026-03-01T09:00:00Z"
  }
}

Create a new draft. The post is saved with draft status and is not published until you call the publish endpoint.

Request body (JSON)

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Big news: we just shipped X. Here is what changed...",
    "platforms": ["linkedin", "twitter"]
  }' \
  "https://app.demandbird.com/api/v1/accounts/42/drafts"

Returns 201 Created with the new draft:

{
  "draft": {
    "id": 124,
    "status": "draft",
    "content": "Big news: we just shipped X...",
    "platforms": ["linkedin", "twitter"],
    "scheduled_at": null,
    "published_at": null,
    "created_at": "2026-03-02T10:30:00Z",
    "updated_at": "2026-03-02T10:30:00Z"
  }
}

Update content, platforms, or scheduled time on an existing draft. All fields are optional; only send the fields you want to change.

Request body (JSON)

An edit changes the shared draft only. A channel's own tailored copy is never changed or refused.

curl -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated copy, cleaner and tighter.",
    "platforms": ["linkedin"]
  }' \
  "https://app.demandbird.com/api/v1/accounts/42/drafts/124"

Response:

{
  "draft": {
    "id": 124,
    "status": "draft",
    "content": "Updated copy, cleaner and tighter.",
    "platforms": ["linkedin"],
    ...
  }
}

Publish a draft immediately, or schedule it for a future time, to all selected platforms. The draft must have at least one platform set; update it first if needed.

With no body (or no scheduled_at), the post publishes immediately: status changes to posting, platform jobs are enqueued, and the status transitions to posted (or failed) once complete.

With scheduled_at in the body, the post is scheduled for that time instead: status becomes scheduled, no posting jobs run until the scheduled time arrives. The time must be in the future and parseable as ISO 8601.

Body parameters

Publish immediately:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://app.demandbird.com/api/v1/accounts/42/drafts/124/publish"

Schedule for later:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at": "2026-04-28T09:00:00-07:00"}' \
  "https://app.demandbird.com/api/v1/accounts/42/drafts/124/publish"

Response (immediate):

{
  "draft": {
    "id": 124,
    "status": "posting",
    "content": "Updated copy, cleaner and tighter.",
    "platforms": ["linkedin"],
    "scheduled_at": "2026-03-02T11:00:00Z",
    "published_at": null,
    "created_at": "2026-03-02T10:30:00Z",
    "updated_at": "2026-03-02T11:00:00Z"
  },
  "message": "Post is being published to linkedin"
}

Response (scheduled):

{
  "draft": {
    "id": 124,
    "status": "scheduled",
    "content": "Updated copy, cleaner and tighter.",
    "platforms": ["linkedin"],
    "scheduled_at": "2026-04-28T16:00:00Z",
    "published_at": null,
    "created_at": "2026-03-02T10:30:00Z",
    "updated_at": "2026-03-02T11:00:00Z"
  },
  "message": "Post scheduled for linkedin"
}

published_at populates once the platform confirms the post. Poll GET /drafts/:id to check the final status.

Remove a post by ID. Works for any status: drafts, scheduled, posted, or failed. Returns 204 No Content on success.

curl -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://app.demandbird.com/api/v1/accounts/42/drafts/124"

Empty 204 response on success. 404 if the post doesn't exist or belongs to a different account.

Writes a new draft from an idea, in the user's voice and the workspace's brand. The draft is saved, and its post_id works with every drafts endpoint (get, update, revise, publish).

Request body (JSON)

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 42,
    "prompt": "Why we moved our onboarding calls to async video",
    "platform": "linkedin"
  }' \
  "https://app.demandbird.com/api/v1/compose_drafts"

Returns 201 Created with the saved draft:

{
  "kind": "draft",
  "post_id": 123,
  "content": "Generated text",
  "platform": "linkedin",
  "unsupported_numbers": ["73%"]
}

unsupported_numbers lists numbers the AI wrote that weren't in your prompt, so you can check them before publishing. It's [] when there are none. platform is null if you didn't send one.

If the AI needs more to go on, it returns 200 OK with a question and saves nothing:

{
  "kind": "need_more",
  "ask": "Which audience is this for?"
}

Add the detail to prompt and send again, or send draft_anyway: true.

Errors

Rewrites the same draft from your feedback (“make it shorter”, “less salesy”). The draft keeps its images, schedule and any per-channel copies. Use this instead of writing a new draft when you're iterating.

Only drafts with status draft or scheduled can be revised.

Request body (JSON)

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"feedback": "Make it shorter and less salesy."}' \
  "https://app.demandbird.com/api/v1/accounts/42/drafts/123/revise"

Returns 200 OK with the revised draft:

{
  "kind": "draft",
  "draft": {
    "id": 123,
    "status": "draft",
    "content": "Revised text",
    "platforms": ["linkedin"],
    "scheduled_at": null,
    "published_at": null,
    "created_at": "2026-03-02T10:30:00Z",
    "updated_at": "2026-03-02T10:45:00Z"
  },
  "unsupported_numbers": []
}

unsupported_numbers works as in Write a draft with AI. If the AI needs more detail, it returns 200 OK and leaves the draft untouched:

{
  "kind": "need_more",
  "ask": "Shorter for which audience?",
  "post_id": 123
}

Errors

Stores a transcript, article or notes with a draft. Reviewers can read it, and the AI writes from it when you revise the draft.

Request body (JSON)

Send exactly one of text or url.

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Kickoff call",
    "text": "Transcript of the kickoff call..."
  }' \
  "https://app.demandbird.com/api/v1/accounts/42/drafts/123/references"

Returns 201 Created:

{
  "reference": {
    "id": 9,
    "idea_source_id": 44,
    "title": "Kickoff call",
    "url": null,
    "kind": "paste"
  },
  "draft": {
    "id": 123,
    "status": "draft",
    "content": "Big news: we just shipped X...",
    "platforms": ["linkedin"],
    ...
  }
}

kind is "paste" for text and "url" for url.

Errors

Returns the next open slot in the posting queue for each platform. Pass the time to publish as scheduled_at.

Query parameters

curl -g -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/queue_slots?account_id=42&platforms[]=linkedin&platforms[]=twitter"

Response:

{
  "slots": {
    "linkedin": "2026-09-23T09:00:00Z",
    "twitter": null
  }
}

null means no queue slots are set up for that platform.

Errors

Returns a paginated list of posts with posted status, ordered by most-recently-updated. Filter by date range with sinceand until.

Query parameters

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/posts"

# Filter by date range
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/posts?since=2026-03-01T00:00:00Z"

Response:

{
  "posts": [
    {
      "id": 121,
      "status": "posted",
      "content": "Post that went live yesterday...",
      "platforms": ["linkedin"],
      "scheduled_at": "2026-03-01T08:00:00Z",
      "published_at": "2026-03-01T08:01:32Z",
      "created_at": "2026-02-28T20:00:00Z",
      "updated_at": "2026-03-01T08:01:32Z"
    }
  ],
  "meta": {
    "page": 1,
    "items": 20,
    "count": 8,
    "pages": 1
  }
}