Developer API Reference

Create, manage, and publish social media drafts programmatically. All endpoints require an API token: generate one in your account settings.

Prefer natural language? Use DemandBird inside Claude →
Business

The REST API is available on the Business and Agency plans. See plans & what's included.

Authentication

Every request must include your API token as a Bearer token in the Authorization header. Generate a token from Settings → API Tokens — see API tokens for how to scope and revoke one.

Authorization: Bearer YOUR_API_TOKEN
Keep your API token secret. Treat it like a password; don't commit it to source code or expose it in client-side JavaScript.

Permissions

A token can be limited to certain actions when it's created. Writing needs the “compose posts” permission, the AI endpoints need “use AI generation”, publishing needs “publish posts” and deleting needs “delete posts”. A token never has more rights than the person who made it.

A request the token isn't allowed to make returns 403:

{"success": false, "error": "You are not authorized to perform this action."}

Base URL

All API endpoints are relative to:

https://app.demandbird.com/api/v1/accounts/{account_id}

Your account_id is the numeric ID shown in your account settings. All endpoints are scoped to a single account; you cannot access another account's data even with a valid token.

Two endpoints sit outside this prefix: Write a draft with AI and Next free queue slot. They live at https://app.demandbird.com/api/v1/ and take account_id as a parameter instead.

Rate limits

1,000
requests per hour
60
requests per minute (burst)

When you exceed a limit the API returns 429 Too Many Requests with headers:

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 1735689600

{"error": "Rate limit exceeded. Try again later."}

Wait until RateLimit-Reset (Unix timestamp) before retrying.

Errors

StatusMeaning
401 UnauthorizedMissing or invalid API token.
403 ForbiddenToken is valid but you don't have access to this account, or the token lacks the permission for this action.
404 Not FoundDraft or resource not found.
422 Unprocessable EntityValidation failed. Check the errors array in the response body.
429 Too Many RequestsRate limit exceeded.
500 Internal Server ErrorSomething went wrong on our end.

Error responses always include an error or errors key:

{"error": "Draft not found"}

{"errors": ["Content can't be blank", "Platforms can't be empty"]}

List drafts

GET/drafts

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

Query parameters

ParameterTypeDescription
statusoptionalstringFilter by status. One of: draft, scheduled, posted, failed. Defaults to returning draft and scheduled combined.
pageoptionalintegerPage number. Defaults to 1. Returns 20 results per page.
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
  }
}

Get a draft

GET/drafts/:id

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 draft

POST/drafts

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

Request body (JSON)

FieldTypeDescription
contentrequiredstringThe text content of the post.
platformsoptionalarrayPlatforms to publish to. Supported values: linkedin, twitter, threads, bluesky, substack, tiktok, youtube, instagram.
scheduled_atoptionalstring (ISO 8601)Stores an intended publish time on the draft for reference. This does not schedule the post for publishing. To schedule, call publish with scheduled_at in the body.
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 a draft

PATCH/drafts/:id

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)

FieldTypeDescription
contentoptionalstringNew text content for the post.
platformsoptionalarrayReplaces the current platform selection.
scheduled_atoptionalstring (ISO 8601)Update the stored intended publish time on the draft. As with create, this stores a reference time only; it does not schedule the post.
on_variant_conflictoptionalstringAccepted for older clients and ignored.

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 or schedule a draft

POST/drafts/:id/publish

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

ParameterTypeDescription
scheduled_atoptionalstring (ISO 8601)If present and in the future, schedules the post for that time instead of publishing immediately. Past or malformed values return 422.
platform_account_idsoptionalobjectMap of platform to connected-account id (e.g. {"twitter": 42}) when an account has multiple connections for a platform. Each id must belong to the current account and match the platform.
Immediate publishing is irreversible. Scheduled posts can still be edited or removed before their scheduled time.

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.

Delete a post

DELETE/drafts/:id

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

For posts already published to a platform: this removes the DemandBird record (and its analytics linkage); the live copy on the platform stays put. To take down the live post, delete it on the platform itself.
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.

Write a draft with AI

POST/api/v1/compose_drafts

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)

FieldTypeDescription
account_idrequiredintegerThe account to write the draft in. Not needed if the token is scoped to one account.
promptrequiredstringThe idea to write about.
platformoptionalstringlinkedin, twitter, bluesky or threads shape the length of the draft.
draft_anywayoptionalbooleanWrite the draft even if the AI would ask for more detail first.
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

StatusMeaning
403The token lacks the “use AI generation” permission.
422{"error": "prompt is required"}
502{"error": "AI service error: …"}
503{"error": "AI service not configured"}

Revise a draft with AI

POST/api/v1/accounts/{account_id}/drafts/{id}/revise

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)

FieldTypeDescription
feedbackrequiredstringWhat to change.
platformoptionalstringSets the length target only. It never changes the draft's platforms.
draft_anywayoptionalbooleanRevise even if the AI would ask for more detail first.
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

StatusMeaning
403The token lacks the “use AI generation” permission.
404{"error": "Draft not found"}
422{"error": "feedback is required"}
422The draft is already posted or has no text.
422The account's AI allowance is used up.
502{"error": "AI service error: …"}
503{"error": "AI service not configured"}

Attach source material

POST/api/v1/accounts/{account_id}/drafts/{id}/references

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

Source material is never published. Put it here, never in the draft's content, because content is what gets published.

Request body (JSON)

Send exactly one of text or url.

FieldTypeDescription
textone ofstringThe material itself.
urlone ofstringA link to the material. We fetch it for you.
titleoptionalstringA label for the material.
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

StatusMeaning
403The token lacks the permission for this action.
404{"error": "Draft not found"}
422Both or neither of text and url were given.
422The URL couldn't be fetched.

Next free queue slot

GET/api/v1/queue_slots

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

Query parameters

ParameterTypeDescription
account_idintegerThe account whose queue to check.
platforms[]requiredstringA platform to check. Repeat for each platform.
platform_account_ids[<platform>]optionalintegerPicks one connected account for a platform, e.g. platform_account_ids[twitter]=7.
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

StatusMeaning
422{"error": "platforms parameter is required"}
422None of the listed platforms is supported.

List published posts

GET/posts

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

Query parameters

ParameterTypeDescription
sinceoptionalstring (ISO 8601)Return posts updated at or after this timestamp.
untiloptionalstring (ISO 8601)Return posts updated at or before this timestamp.
pageoptionalintegerPage number. Defaults to 1.
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
  }
}

Analytics

The analytics endpoints return the same numbers as the Analytics tab in the app, as JSON. They only read data. The token's owner needs a role that can view analytics; anyone else gets a 403. These rules apply to every analytics endpoint below:

  • Time window. Pass period (7d, 30d or 90d, default 30d), or a custom range with start_date and end_date as YYYY-MM-DD. Dates are in the user's time zone, win over period, and can cover up to 366 days. Each response says which window it used in period.
  • Rates are percentages. 12.5 means 12.5%.
  • Missing is null, never 0. A number a platform doesn't report (for example impressions on Bluesky) is null or left out, so you can tell “not reported” apart from “zero”.
  • Nothing to show is not an error. When there is no data yet, or a platform doesn't offer this, the answer is 200 with a message field that says why, and no numbers. Check for message before reading the rest.
  • Platforms. platform takes linkedin, twitter, threads, bluesky, facebook, instagram, mastodon, youtube, tiktok or pinterest. An unknown one is a 422.
{"message": "Not enough data yet to find your best times on X."}

Account summary

GET/api/v1/accounts/{account_id}/analytics/summary

Followers, engagements, reach or impressions, and engagement rate for a period, each compared with the period before.

Query parameters

ParameterTypeDescription
platformoptionalstringOne network. Leave it out for every connected network at once.
periodoptionalstringRolling window ending today: 7d, 30d or 90d. Defaults to 30d.
start_dateoptionalstring (YYYY-MM-DD)First day of a custom range. Overrides period.
end_dateoptionalstring (YYYY-MM-DD)Last day of a custom range, inclusive. Defaults to today.
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/analytics/summary?platform=linkedin&period=30d"

Response:

{
  "period": {
    "key": "30d",
    "label": "the last 30 days",
    "from": "2026-10-11T00:00:00-05:00",
    "to": "2026-11-10T23:59:59-06:00"
  },
  "summary": {
    "platform": "linkedin",
    "followers": {"current": 4210, "change": 86},
    "engagements": {"current": 512, "prior": 430, "change_pct": 19.07},
    "volume": {"current": 13940, "prior": 12100, "change_pct": 15.21, "label": "impressions"},
    "engagement_rate": 3.67,
    "posts": 12,
    "premium_cta_clicks": null,
    "last_synced_at": "2026-11-10T06:00:00Z"
  },
  "company_pages": null,
  "reactions": {
    "collected": true,
    "not_collected_reason": null,
    "total": 380,
    "types": [{"type": "Like", "count": 301}, {"type": "Insightful", "count": 79}],
    "posts_covered": 12,
    "posts_total": 12
  }
}

Without platform, the answer has platforms (one summary like the one above per network), totals (followers and engagements) and skipped (each left-out network with a reason) instead of summary. reactions is LinkedIn only.

Top posts

GET/api/v1/accounts/{account_id}/analytics/top_posts

Posts ranked best to worst (or worst to best) by one metric.

Query parameters

ParameterTypeDescription
authoroptionalstringme for the token's owner, or a teammate's name. Leave it out for the whole workspace.
platformoptionalstringOne network. Leave it out to rank across all of them.
metricoptionalstringWhat to rank by. Defaults to engagement_rate. Also engagements, reach, likes, comments, shares, impressions, clicks, saves, video_views and more. A metric the platform doesn't report is a 422 that lists the ones it does.
orderoptionalstringtop (default) or bottom.
periodoptionalstringRolling window ending today: 7d, 30d or 90d. Defaults to 30d.
start_dateoptionalstring (YYYY-MM-DD)First day of a custom range. Overrides period.
end_dateoptionalstring (YYYY-MM-DD)Last day of a custom range, inclusive. Defaults to today.
limitoptionalintegerHow many posts. Default 5, max 20.
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/analytics/top_posts?platform=linkedin&metric=engagements&limit=3"

Response:

{
  "period": {
    "key": "30d",
    "label": "the last 30 days",
    "from": "2026-10-11T00:00:00-05:00",
    "to": "2026-11-10T23:59:59-06:00"
  },
  "metric": "engagements",
  "order": "top",
  "platforms": ["linkedin"],
  "posts": [
    {
      "post_id": 8812,
      "composition_id": 124,
      "platform": "linkedin",
      "posted_at": "2026-11-03T14:00:00Z",
      "url": "https://www.linkedin.com/feed/update/urn:li:activity:7390000000000000000/",
      "text": "Three things we learned shipping our pricing page...",
      "author": {"id": 7, "name": "Jane Doe"},
      "metrics": {
        "engagement_rate": 4.12,
        "engagements": 96,
        "reach": 2330,
        "likes": 71,
        "comments": 18,
        "shares": 7
      },
      "metric_value": 96
    }
  ]
}

post_id is the published post's id. Use it with Post analytics and Tag a published post. composition_id is the draft it came from, or null for a post made outside DemandBird.

All posts with numbers

GET/api/v1/accounts/{account_id}/analytics/posts

Every published post in a date range with all its numbers, newest first, one page at a time. Use it for a full export.

Query parameters

ParameterTypeDescription
authoroptionalstringme for the token's owner, or a teammate's name. Leave it out for the whole workspace.
platformoptionalstringOne network. Leave it out for all of them.
periodoptionalstring7d, 30d or 90d. Defaults to 30d.
start_dateoptionalstring (YYYY-MM-DD)First day of the range. Overrides period. Here the range can be longer than a year.
end_dateoptionalstring (YYYY-MM-DD)Last day of the range, inclusive. Defaults to today.
limitoptionalintegerPosts per page. Default 50, max 100.
cursoroptionalstringThe next_cursor from the previous page. Leave it out for the first page. A cursor that isn't one is a 422.
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/analytics/posts?start_date=2026-01-01&limit=100"

Response:

{
  "period": {"key": "custom", "label": "Jan 1 to Nov 10, 2026", "from": "2026-01-01T00:00:00-06:00", "to": "2026-11-10T23:59:59-06:00"},
  "platforms": ["linkedin", "twitter"],
  "posts": [
    {
      "post_id": 8812,
      "composition_id": 124,
      "platform": "linkedin",
      "posted_at": "2026-11-03T14:00:00Z",
      "url": "https://www.linkedin.com/feed/update/urn:li:activity:7390000000000000000/",
      "text": "Three things we learned shipping our pricing page...",
      "author": {"id": 7, "name": "Jane Doe"},
      "metrics": {
        "engagement_rate": 4.12,
        "engagements": 96,
        "reach": 2330,
        "likes": 71,
        "comments": 18,
        "shares": 7
      }
    }
  ],
  "next_cursor": "eyJwIjoiMjAyNi0xMS0wMyJ9"
}

To get the next page, send the same request again with cursor set to next_cursor. The last page has "next_cursor": null. Numbers are as of the latest sync, so recent posts are still growing.

Post analytics

GET/api/v1/accounts/{account_id}/analytics/post

Every number DemandBird has for one published post, including how it built up over time.

Query parameters

ParameterTypeDescription
post_idoptionalintegerThe published post's id, from top posts, all posts or search.
composition_idoptionalintegerOr the id of the DemandBird draft it came from (the id the drafts endpoints use).
latestoptionalbooleanOr true for the most recent published post.
platformoptionalstringWith latest, the newest post on this network.

Send one of post_id, composition_id or latest=true. With none, the answer is a 422.

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/analytics/post?post_id=8812"

Response:

{
  "post": {
    "post_id": 8812,
    "composition_id": 124,
    "platform": "linkedin",
    "posted_at": "2026-11-03T14:00:00Z",
    "url": "https://www.linkedin.com/feed/update/urn:li:activity:7390000000000000000/",
    "text": "Three things we learned shipping our pricing page...",
    "author": {"id": 7, "name": "Jane Doe"},
    "metrics": {"engagement_rate": 4.12, "engagements": 96, "reach": 2330, "saves": 4},
    "tags": ["Launch"],
    "engagements": 96,
    "velocity": [
      {"at": "2026-11-03T15:00:00Z", "value": 410},
      {"at": "2026-11-04T14:00:00Z", "value": 1890}
    ],
    "reactions": null,
    "video": null,
    "youtube": null
  }
}

video has views, viewers, watch_time_ms and average_watch_time_ms for a video post. If no post matches, the answer is {"message": "No matching post found."}.

Best times to post

GET/api/v1/accounts/{account_id}/analytics/best_times

The day and hour slots where past posts did best, in the user's time zone. This is past results, not the posting schedule.

Query parameters

ParameterTypeDescription
platformrequiredstringThe network to look at.
periodoptionalstringRolling window ending today: 7d, 30d or 90d. Defaults to 30d.
start_dateoptionalstring (YYYY-MM-DD)First day of a custom range. Overrides period.
end_dateoptionalstring (YYYY-MM-DD)Last day of a custom range, inclusive. Defaults to today.
limitoptionalintegerHow many slots. Default 3, max 10.
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/analytics/best_times?platform=linkedin&period=90d"

Response:

{
  "period": {
    "key": "30d",
    "label": "the last 30 days",
    "from": "2026-10-11T00:00:00-05:00",
    "to": "2026-11-10T23:59:59-06:00"
  },
  "platform": "linkedin",
  "time_zone": "America/Chicago",
  "measure": "median_engagement_rate",
  "slots": [
    {"day": "Tuesday", "weekday": 2, "hour": 9, "label": "Tuesday 9am", "value": 5.4, "posts": 6},
    {"day": "Thursday", "weekday": 4, "hour": 14, "label": "Thursday 2pm", "value": 4.1, "posts": 4}
  ]
}

measure says what value is: median_engagement_rate (a percentage) where the platform reports impressions, otherwise median_engagements (a count). posts is how many posts the slot is based on. Too few posts gives a message instead.

Format performance

GET/api/v1/accounts/{account_id}/analytics/formats

Post formats (text, image, video and so on) ranked by engagement. On LinkedIn it covers personal profiles only, not company pages.

Query parameters

ParameterTypeDescription
platformrequiredstringThe network to look at.
periodoptionalstringRolling window ending today: 7d, 30d or 90d. Defaults to 30d.
start_dateoptionalstring (YYYY-MM-DD)First day of a custom range. Overrides period.
end_dateoptionalstring (YYYY-MM-DD)Last day of a custom range, inclusive. Defaults to today.
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/analytics/formats?platform=linkedin"

Response:

{
  "period": {
    "key": "30d",
    "label": "the last 30 days",
    "from": "2026-10-11T00:00:00-05:00",
    "to": "2026-11-10T23:59:59-06:00"
  },
  "platform": "linkedin",
  "measure": "median_engagement_rate",
  "formats": [
    {"format": "Document", "value": 6.2, "posts": 3, "vs_typical": 1.6},
    {"format": "Text only", "value": 3.8, "posts": 14, "vs_typical": 1.0}
  ]
}

measure works as in Best times to post. posts and vs_typical (how many times your typical post) are left out where the platform doesn't have them.

Audience demographics

GET/api/v1/accounts/{account_id}/analytics/demographics

Who your followers are, where the platform reports it: Instagram and Threads (country, age, gender, city) and LinkedIn company pages (seniority, job function, industry, company size, location). Other platforms answer with a message.

Query parameters

ParameterTypeDescription
platformrequiredstringThe network to look at.
periodoptionalstringRolling window ending today: 7d, 30d or 90d. Defaults to 30d.
start_dateoptionalstring (YYYY-MM-DD)First day of a custom range. Overrides period.
end_dateoptionalstring (YYYY-MM-DD)Last day of a custom range, inclusive. Defaults to today.
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/analytics/demographics?platform=instagram"

Response:

{
  "platform": "instagram",
  "source": "accounts",
  "sections": [
    {
      "name": "country",
      "segments": [
        {"label": "US", "count": 1820, "share_pct": 61.5},
        {"label": "GB", "count": 410, "share_pct": 13.85}
      ]
    }
  ]
}

source is accounts, or linkedin_company_page when the numbers come from a LinkedIn company page.

Follower history

GET/api/v1/accounts/{account_id}/analytics/follower_history

Follower count for each day, per LinkedIn profile or company page. LinkedIn only: another platform is a 422.

Query parameters

ParameterTypeDescription
accountoptionalstringOne LinkedIn profile or page, by its name or its connected account id. Leave it out for every LinkedIn channel.
platformoptionalstringDefaults to linkedin.
periodoptionalstringRolling window ending today: 7d, 30d or 90d. Defaults to 30d.
start_dateoptionalstring (YYYY-MM-DD)First day of a custom range. Overrides period.
end_dateoptionalstring (YYYY-MM-DD)Last day of a custom range, inclusive. Defaults to today.
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/analytics/follower_history?period=7d"

Response:

{
  "period": {
    "key": "30d",
    "label": "the last 30 days",
    "from": "2026-10-11T00:00:00-05:00",
    "to": "2026-11-10T23:59:59-06:00"
  },
  "channels": [
    {
      "connected_account_id": 15,
      "name": "Jane Doe",
      "kind": "profile",
      "tracking_since": "2026-02-01",
      "days": [
        {"date": "2026-11-09", "followers": 4198},
        {"date": "2026-11-10", "followers": 4210}
      ],
      "missing_days": 0,
      "net_change": 12
    }
  ]
}

kind is profile or company_page. Days with no reading are left out of days and counted in missing_days.

Tag a published post

PUT/api/v1/accounts/{account_id}/posts/{id}/tags

Sets the tags on a post that is already out, by the post_id the analytics endpoints return. Works on posts imported from the platform or posted outside DemandBird too. For a draft or scheduled post, use Update a draft instead.

Request body (JSON)

FieldTypeDescription
tagsrequiredarray of stringsTag names. Replaces the whole set; [] removes them all. Matched ignoring case. A new name becomes a new tag if the user may create tags; otherwise nothing changes and the answer is an error.
curl -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["Launch", "Case study"]}' \
  "https://app.demandbird.com/api/v1/accounts/42/posts/8812/tags"

Response:

{
  "post_id": 8812,
  "tags": ["Case study", "Launch"],
  "message": "Tags on LinkedIn post (post_id 8812): Case study, Launch."
}

Leaving out tags is a 422. A post that isn't on this account is a 404.

Search published posts

GET/api/v1/accounts/{account_id}/posts/search

Finds published posts by their words, newest first. Covers every post on the workspace's channels, including imported history.

Query parameters

ParameterTypeDescription
queryrequiredstringThe words to look for. Every word must appear (case does not matter). Use a few distinctive words, not a sentence.
authoroptionalstringme for the token's owner, or a teammate's name. Leave it out for the whole workspace.
platformoptionalstringOne network. Leave it out for all of them.
start_dateoptionalstring (YYYY-MM-DD)Only posts on or after this day. Leave out both dates for all time.
end_dateoptionalstring (YYYY-MM-DD)Only posts on or before this day.
limitoptionalintegerHow many matches. Default 10, max 25. There are no further pages: narrow the search to see more.
curl -G -H "Authorization: Bearer YOUR_TOKEN" \
     --data-urlencode "query=pricing page" \
     "https://app.demandbird.com/api/v1/accounts/42/posts/search"

Response:

{
  "total": 1,
  "posts": [
    {
      "post_id": 8812,
      "composition_id": 124,
      "platform": "linkedin",
      "posted_at": "2026-11-03T14:00:00Z",
      "url": "https://www.linkedin.com/feed/update/urn:li:activity:7390000000000000000/",
      "text": "Three things we learned shipping our pricing page...",
      "author": {"id": 7, "name": "Jane Doe"},
      "metrics": {
        "engagements": 15,
        "engagement_rate": 3.75,
        "reach": 400,
        "likes": 12,
        "comments": 2,
        "shares": 1
      }
    }
  ]
}

total is how many posts matched in all. Each match carries its latest numbers, the same metrics as Posts with metrics (null until a post has been measured). Pass the post_id to Post analytics for the full detail. No match is {"total": 0, "posts": []}.

Scheduled posts

GET/api/v1/accounts/{account_id}/scheduled_posts

What is scheduled to go out, in the order it goes. Posts that missed their time come back on their own in past_due_posts, oldest first.

Query parameters

ParameterTypeDescription
windowoptionalstringtoday (the workspace's calendar day, up to 10 posts), week (the next 7 days, up to 15) or upcoming (everything ahead, up to 10). Defaults to upcoming.
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/scheduled_posts?window=week"

Response:

{
  "posts": [
    {
      "id": 124,
      "status": "scheduled",
      "editorial_status": "ready_to_schedule",
      "content": "Three things we learned shipping our pricing page...",
      "platforms": ["linkedin"],
      "author": {"id": 7, "name": "Jane Doe"},
      "media": [],
      "scheduled_at": "2026-11-12T09:00:00-05:00",
      "penciled_at": null,
      "published_at": null,
      "created_at": "2026-11-09T15:20:00Z",
      "updated_at": "2026-11-10T08:00:00Z",
      "reviews": []
    }
  ],
  "past_due_posts": []
}

Each post has the same fields as Get a draft. Times are in the workspace's posting time zone.

Posting schedule

GET/api/v1/accounts/{account_id}/queue/schedule

Each channel's weekly posting times (the queue times on the Posting Schedule page) and the days they run on.

Query parameters

ParameterTypeDescription
platformoptionalstringOnly this platform's channels. Leave it out for all of them.
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/queue/schedule?platform=linkedin"

Response:

{
  "time_zone": "America/Chicago",
  "channels": [
    {
      "connected_account_id": 15,
      "platform": "linkedin",
      "name": "Jane Doe",
      "times": [
        {"time": "09:00", "days": ["monday", "tuesday", "wednesday", "thursday", "friday"]},
        {"time": "14:30", "days": ["saturday"]}
      ],
      "editable": true
    }
  ]
}

Times are 24-hour clock times in time_zone, the workspace's posting time zone. editable is false when only the person who connected the channel or an account admin can change it.

Add posting times

POST/api/v1/accounts/{account_id}/queue/times

Adds times to one channel's weekly schedule. A time already there is left as it is. Posts already in the queue keep their times.

Request body (JSON)

FieldTypeDescription
platformrequiredstringThe channel's platform.
timesrequiredarray of strings24-hour HH:MM times, e.g. ["09:00", "14:30"], in the workspace's posting time zone.
daysrequiredarray of stringsDay names (monday to sunday), or everyday, weekdays or weekends.
platform_account_idsoptionalobjectWhich channel, when the platform has more than one: {"linkedin": 15}, with ids from the posting schedule.
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"platform": "linkedin", "times": ["09:00", "17:00"], "days": ["monday", "tuesday"]}' \
  "https://app.demandbird.com/api/v1/accounts/42/queue/times"

Response:

{
  "added": {"09:00": ["tuesday"], "17:00": ["monday", "tuesday"]},
  "already_there": {"09:00": ["monday"]},
  "failed": [],
  "time_zone": "America/Chicago",
  "schedule": {
    "connected_account_id": 15,
    "platform": "linkedin",
    "name": "Jane Doe",
    "times": [
      {"time": "09:00", "days": ["monday", "tuesday"]},
      {"time": "17:00", "days": ["monday", "tuesday"]}
    ]
  }
}

schedule is the channel's schedule after the change. A time that isn't HH:MM is a 422 and nothing is written.

Remove posting times

DELETE/api/v1/accounts/{account_id}/queue/times

Removes times from one channel's weekly schedule. Without days, a time is removed from every day. Posts already in the queue keep their times.

Request body (JSON)

FieldTypeDescription
platformrequiredstringThe channel's platform.
timesrequiredarray of strings24-hour HH:MM times to remove.
daysoptionalarray of stringsOnly these days. Same values as when adding.
platform_account_idsoptionalobjectWhich channel, when the platform has more than one.
curl -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"platform": "linkedin", "times": ["09:00", "18:00"]}' \
  "https://app.demandbird.com/api/v1/accounts/42/queue/times"

Response:

{
  "removed": {"09:00": ["monday", "tuesday", "wednesday", "thursday", "friday"]},
  "not_found": ["18:00"],
  "time_zone": "America/Chicago",
  "schedule": {
    "connected_account_id": 15,
    "platform": "linkedin",
    "name": "Jane Doe",
    "times": [{"time": "12:00", "days": ["monday"]}]
  }
}

If none of the times were on the schedule, the answer is a 404.

Pause the queue

POST/api/v1/accounts/{account_id}/queue/pause

Stops publishing for the whole account, every workspace included. Scheduled posts stay on the calendar and wait; nothing is deleted or moved. No body.

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

Response:

{
  "paused": true,
  "changed": true,
  "paused_at": "2026-11-10T15:04:00Z",
  "scheduled_posts": 6
}

changed is false when the queue was already paused. scheduled_posts is how many posts are waiting.

Resume the queue

POST/api/v1/accounts/{account_id}/queue/resume

Starts publishing again for the whole account. Scheduled posts keep their times. No body.

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

Response:

{
  "paused": false,
  "changed": true,
  "paused_at": null,
  "scheduled_posts": 6
}

changed is false when the queue wasn't paused.

Pipeline status

GET/api/v1/accounts/{account_id}/status

Counts of what is in the pipeline. Counts only: for followers, engagement or reach, use the analytics endpoints.

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

Response:

{
  "drafts": 14,
  "scheduled": 6,
  "past_due": 1,
  "posted_today": 2,
  "queue_paused": false
}

past_due is scheduled posts that missed their time; they are counted in scheduled too. posted_today counts from midnight server time.

Ask for a review

POST/api/v1/accounts/{account_id}/drafts/{id}/review

Asks one or more teammates to review a draft. Required reviewers block publishing until every one approves; optional ones don't.

Request body (JSON)

FieldTypeDescription
reviewersrequiredarray of objectsOne object per reviewer, naming them by email, user_id or name. Add "required": false for an optional reviewer (the default is true). An unknown or ambiguous name is a 422 and nobody is asked.
noteoptionalstringA message to the reviewers.
scheduled_atoptionalstring (ISO 8601)The post goes out at this time, once every required reviewer has approved.
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reviewers": [{"user_id": 9, "required": true}], "note": "Before Friday please"}' \
  "https://app.demandbird.com/api/v1/accounts/42/drafts/124/review"

Response:

{
  "draft": {
    "id": 124,
    "status": "draft",
    "editorial_status": "internal_review",
    "content": "Three things we learned shipping our pricing page...",
    "platforms": ["linkedin"],
    "reviews": [
      {
        "reviewer": {"id": 9, "name": "Sam Lee"},
        "external": false,
        "stage": "internal",
        "required": true,
        "status": "pending",
        "requested_at": "2026-11-10T14:00:00Z",
        "responded_at": null,
        "note": null
      }
    ]
  }
}

Returns 201 Created with the draft and its reviews (trimmed above).

Posts waiting on my review

GET/api/v1/accounts/{account_id}/reviews/awaiting

Posts teammates asked the token's owner to review that still need a verdict, most recently changed first. Covers every workspace on the account.

Query parameters

ParameterTypeDescription
limitoptionalintegerDefault 20, max 100.
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/reviews/awaiting"

Response:

{
  "drafts": [
    {
      "id": 124,
      "status": "draft",
      "editorial_status": "internal_review",
      "content": "Three things we learned shipping our pricing page...",
      "platforms": ["linkedin"],
      "reviews": [
        {
            "reviewer": {"id": 9, "name": "Sam Lee"},
            "external": false,
            "stage": "internal",
            "required": true,
            "status": "pending",
            "requested_at": "2026-11-10T14:00:00Z",
            "responded_at": null,
            "note": null
          }
      ]
    }
  ]
}

Nothing waiting is {"drafts": []}.

Approve a post

POST/api/v1/accounts/{account_id}/drafts/{id}/approve

Approves a post the token's owner was asked to review. The verdict is recorded straight away: there is no confirmation link, unlike approving through Claude.

Request body (JSON)

FieldTypeDescription
noteoptionalstringA note to the author, saved with the approval.
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note": "Looks great"}' \
  "https://app.demandbird.com/api/v1/accounts/42/drafts/124/approve"

Response:

{
  "draft": {
    "id": 124,
    "status": "draft",
    "content": "Three things we learned shipping our pricing page...",
    "platforms": ["linkedin"],
    "reviews": [
      {
        "reviewer": {"id": 9, "name": "Sam Lee"},
        "external": false,
        "stage": "internal",
        "required": true,
        "status": "approved",
        "requested_at": "2026-11-10T14:00:00Z",
        "responded_at": "2026-11-10T16:30:00Z",
        "note": null
      }
    ]
  }
}

A 422 if the token's owner isn't a reviewer on this post or has already given a verdict. A 404 if the post doesn't exist.

Send a post back

POST/api/v1/accounts/{account_id}/drafts/{id}/send_back

Sends a post back to its author with what needs to change. Like approve, the verdict is recorded straight away with no confirmation link. For a required review, the post moves to revision_requested.

Request body (JSON)

FieldTypeDescription
noterequiredstringWhat needs to change. The author sees it word for word. A blank note is a 400 and nothing is recorded.
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note": "The opening line buries the point."}' \
  "https://app.demandbird.com/api/v1/accounts/42/drafts/124/send_back"

Response:

{
  "draft": {
    "id": 124,
    "status": "draft",
    "editorial_status": "revision_requested",
    "content": "Three things we learned shipping our pricing page...",
    "platforms": ["linkedin"],
    "reviews": [
      {
        "reviewer": {"id": 9, "name": "Sam Lee"},
        "external": false,
        "stage": "internal",
        "required": true,
        "status": "rejected",
        "requested_at": "2026-11-10T14:00:00Z",
        "responded_at": "2026-11-10T16:30:00Z",
        "note": "The opening line buries the point."
      }
    ]
  }
}

The same 422 and 404 cases as approve apply.

Comment on a post

POST/api/v1/accounts/{account_id}/drafts/{id}/comments

Leaves a comment on a post. It decides and blocks nothing. The author and the other reviewers are notified.

Request body (JSON)

FieldTypeDescription
commentrequiredstringThe comment, stored as written. An empty comment is a 400.
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"comment": "Can we cut the second paragraph?"}' \
  "https://app.demandbird.com/api/v1/accounts/42/drafts/124/comments"

Response:

{
  "comment": {
    "id": 77,
    "body": "Can we cut the second paragraph?",
    "author": {"id": 9, "name": "Sam Lee"},
    "created_at": "2026-11-10T16:10:00Z"
  },
  "draft": {
    "id": 124,
    "status": "draft",
    "content": "Three things we learned shipping our pricing page..."
  }
}

Returns 201 Created. draft has the same fields as Get a draft (trimmed above).

List ideas

GET/api/v1/accounts/{account_id}/ideas

Ideas on the Ideas tab of the workspace, newest first. References come back as details only (title, link, kind), never their text.

Query parameters

ParameterTypeDescription
authoroptionalstringA teammate's name, or me. Defaults to the token's owner. Only people who can see everyone's posts may list someone else's.
limitoptionalintegerDefault 20, max 100.
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/ideas?limit=50"

Response:

{
  "ideas": [
    {
      "id": 31,
      "content": "Why cold email still works",
      "author": {"id": 7, "name": "Jane Doe"},
      "tags": ["Launch"],
      "references": [
        {"id": 5, "kind": "paste", "title": "Call notes", "url": null}
      ],
      "workspace_id": 3,
      "created_at": "2026-11-10T09:00:00Z",
      "updated_at": "2026-11-10T09:00:00Z"
    }
  ]
}

Save ideas

POST/api/v1/accounts/{account_id}/ideas

Saves up to 100 ideas in one call. They are all saved or none are. No AI: the text is stored as given.

Request body (JSON)

FieldTypeDescription
ideasrequiredarray of objectsEach has content (required, up to 5,000 characters), and optionally tags (names) and references (up to 20, each with text, url and an optional title). Put source material in references, never in content.
authoroptionalstringWhose ideas these are: a teammate's name, or me. Applies to every idea in the call.
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ideas": [{"content": "Why cold email still works", "tags": ["Launch"], "references": [{"title": "Call notes", "text": "Notes from the Acme call..."}]}]}' \
  "https://app.demandbird.com/api/v1/accounts/42/ideas"

Response:

{
  "ideas": [
    {
      "id": 31,
      "content": "Why cold email still works",
      "author": {"id": 7, "name": "Jane Doe"},
      "tags": ["Launch"],
      "references": [
        {"id": 5, "kind": "paste", "title": "Call notes", "url": null}
      ],
      "workspace_id": 3,
      "created_at": "2026-11-10T09:00:00Z",
      "updated_at": "2026-11-10T09:00:00Z"
    }
  ]
}

Returns 201 Created. An empty ideas list is a 422 and nothing is saved.

Update an idea

PATCH/api/v1/accounts/{account_id}/ideas/{id}

Edits one idea. It keeps its id, and only what you send changes. Only the idea's author or an account admin can edit it.

Request body (JSON)

FieldTypeDescription
contentoptionalstringNew text, up to 5,000 characters. Replaces the old text.
tagsoptionalarray of stringsReplaces the idea's tags. [] removes them all.
referencesoptionalarray of objectsSource material to add, same shape as when saving.
curl -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Why cold email still works in 2027", "tags": ["Case study"]}' \
  "https://app.demandbird.com/api/v1/accounts/42/ideas/31"

Response:

{
  "ideas": [
    {
      "id": 31,
      "content": "Why cold email still works in 2027",
      "tags": ["Case study"]
    }
  ]
}

ideas holds the one updated idea, with every field shown in List ideas (trimmed above). Sending nothing to change is a 422; an idea that isn't there is a 404.

Delete an idea

DELETE/api/v1/accounts/{account_id}/ideas/{id}

Deletes one idea with its sources, tags and images. There is no undo.

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

Response:

{
  "deleted_ids": [31]
}

An idea that isn't on this account is a 404.

Get brand voice

GET/api/v1/accounts/{account_id}/brand_voice

The workspace's brand (positioning, audience, content pillars) and the token owner's writing voice, as one block of text. Read it before you write post copy yourself.

Query parameters

ParameterTypeDescription
platformoptionalstringAlso include recent before-and-after edits made for this platform.
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://app.demandbird.com/api/v1/accounts/42/brand_voice?platform=linkedin"

Response:

{
  "brand_voice": "Brand identity\nPositioning: The scheduler agencies trust\n...\nNever does: uses the word synergy\n..."
}

Update writing voice

PATCH/api/v1/accounts/{account_id}/brand_voice

Changes the token owner's own writing voice, the same edits as Settings → Voice. Never a teammate's. All edits in a call are saved together, or none are.

Request body (JSON)

FieldTypeDescription
editsrequiredarray of objectsOne per field: field, and either value or "reset": true (go back to what was learned from past posts). Fields include identity.positioning, identity.audience, never_does, signature_phrases and voice_signature.warmth. A value replaces the whole field, so to add to a list send the full list.
curl -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"edits": [{"field": "never_does", "value": ["uses the word synergy"]}]}' \
  "https://app.demandbird.com/api/v1/accounts/42/brand_voice"

Response:

{
  "updated_fields": ["never_does"],
  "summary": "Updated your personal voice:\n- Never does: uses the word synergy"
}

An empty edits list is a 422.

Update brand

PATCH/api/v1/accounts/{account_id}/brand

Changes the workspace's positioning and audience, the Brand identity card in Settings → Content topics. A field you send replaces what is there; one you leave out is kept; an empty string clears it.

Request body (JSON)

FieldTypeDescription
positioningoptionalstringWhat the business does and stands for.
icpoptionalstringWho the posts are for (the ideal customer profile, or ICP).
curl -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"positioning": "The scheduler agencies trust"}' \
  "https://app.demandbird.com/api/v1/accounts/42/brand"

Response:

{
  "workspace_id": 3,
  "brand": {
    "positioning": "The scheduler agencies trust",
    "icp": "Agency owners with 5 to 50 clients"
  }
}

Rewrite for another platform

POST/api/v1/accounts/{account_id}/drafts/{id}/tailor

Rewrites a post for another platform with AI, in the user's voice. Counts against the AI allowance like the other AI endpoints.

Request body (JSON)

FieldTypeDescription
platformrequiredstringThe platform to rewrite for. An unknown one is a 422.
save_asoptionalstringnew_draft (default) saves the rewrite as a separate draft. channel_copy saves it on the same post as that platform's own text.
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"platform": "twitter"}' \
  "https://app.demandbird.com/api/v1/accounts/42/drafts/124/tailor"

Response:

{
  "draft": {
    "id": 125,
    "status": "draft",
    "content": "3 things we learned shipping our pricing page:",
    "platforms": ["twitter"]
  },
  "rewrite": "3 things we learned shipping our pricing page:",
  "unsupported_numbers": []
}

Returns 201 Created. draft is the post the rewrite is on (trimmed above). unsupported_numbers works as in Write a draft with AI.

Variations of a draft

POST/api/v1/accounts/{account_id}/drafts/{id}/variations

Three other versions of a post to choose from, written with AI. Nothing is saved. No body.

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

Response:

{
  "variations": [
    "We rebuilt our pricing page three times. Here is what stuck.",
    "Our pricing page taught us three things.",
    "Three lessons from a pricing page nobody read at first."
  ],
  "text": "1. We rebuilt our pricing page three times. Here is what stuck.\n2. Our pricing page taught us three things.\n3. Three lessons from a pricing page nobody read at first.",
  "unsupported_numbers": []
}

text is the model's full answer; variations is the same split into a list. To use one, send it to Update a draft. A post that isn't there is a 404.

Suggest hashtags

POST/api/v1/accounts/{account_id}/drafts/{id}/hashtags

Hashtag ideas for a post (popular, niche and branded) plus one other opening line. Nothing is saved. No body.

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

Response:

{
  "draft_id": 124,
  "hashtags": ["#pricing", "#saas", "#buildinpublic"],
  "text": "Popular: #pricing #saas\nNiche: #buildinpublic\n..."
}

hashtags is every hashtag found in text, without repeats.

Generate an image

POST/api/v1/accounts/{account_id}/generated_images

Makes an original image with AI, in the workspace's brand style. Uses one of the account's monthly image credits. Takes 10 to 30 seconds. The image is also saved to the media library.

Request body (JSON)

FieldTypeDescription
promptrequiredstringWhat the image should show. Describe the picture, not the post. An empty prompt is a 422 and uses no credit.
styleoptionalstringillustration (default), photo, infographic or diagram.
sizeoptionalstringsquare (default, 1:1), portrait (2:3) or landscape (3:2).
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A calm desk at sunrise", "style": "photo"}' \
  "https://app.demandbird.com/api/v1/accounts/42/generated_images"

Response:

{
  "id": 501,
  "s3_key": "editor_uploads/42/ai.png",
  "url": "https://cdn.demandbird.com/editor_uploads/42/ai.png"
}

Returns 201 Created. To attach it, pass images: [{"s3_key": "..."}] when you create or update a draft.

Find someone to tag on LinkedIn

GET/api/v1/accounts/{account_id}/linkedin_mentions

Looks up a person or company page to tag in a LinkedIn post. Send url or name; with neither, the answer is a 422.

Query parameters

ParameterTypeDescription
urloptionalstringA LinkedIn profile or company page link. Always exactly one match.
nameoptionalstringA name to search among people and pages recently tagged on this workspace and the followers of its LinkedIn pages.
connected_account_idoptionalintegerThe LinkedIn channel to look up through. Defaults to one on this workspace that can tag people.
curl -G -H "Authorization: Bearer YOUR_TOKEN" \
     --data-urlencode "name=Jane Doe" \
     "https://app.demandbird.com/api/v1/accounts/42/linkedin_mentions"

Response:

{
  "matches": [
    {"name": "Jane Doe", "urn": "urn:li:person:AbC123", "headline": "Head of Growth at Acme", "kind": "person"}
  ]
}

kind is person or organization. Put the match's name and urn in linkedin_tags on the draft and write @Jane Doe in the text. When several match, ask the user which one; an empty list means ask for their profile link.

Move a draft to another workspace

POST/api/v1/accounts/{account_id}/drafts/{id}/move

Moves a draft saved in the wrong client's workspace. Account admins only. Drafts only: unschedule a scheduled post first. Moving it back undoes it.

Request body (JSON)

FieldTypeDescription
workspacerequiredstringThe workspace to move it to, by name or id. One that doesn't exist is a 422 and nothing moves.
curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspace": "Client B"}' \
  "https://app.demandbird.com/api/v1/accounts/42/drafts/124/move"

Response:

{
  "draft": {
    "id": 124,
    "status": "draft",
    "content": "Three things we learned shipping our pricing page..."
  },
  "workspace_id": 8,
  "from_workspace_id": 3
}

Its tags are matched by name in the new workspace (or created there).

Draft object reference

FieldTypeDescription
idintegerUnique identifier.
statusstringdraft · scheduled · posting · posted · failed
contentstringPlain-text content of the post.
platformsarray of stringsSelected publish targets.
scheduled_atstring or nullISO 8601 timestamp if a schedule was set.
published_atstring or nullISO 8601 timestamp when the post was confirmed published. null until posted.
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 last-updated timestamp.