Posts

Create, list, edit, reschedule, and delete posts and threads.

Postman CollectionDownload the ready-made collection with all endpoints pre-configured.

Use with Claude, ChatGPT & moreConnect any AI assistant to BlackTwist via our MCP server. No code required.

List Posts

`GET /api/v1/posts`

Returns scheduled and published threads within a date range.Query Parameters:

from (required) — Start date, e.g. 2025-03-01T00:00:00
to (required) — End date, e.g. 2025-03-31T23:59:59
providerId (optional) — Filter by provider ID
teamId (optional) — Team ID

Request

curl "https://blacktwist.app/api/v1/posts?from=2025-03-01T00:00:00&to=2025-03-31T23:59:59&providerId=clx...." \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "threads": [
    {
      "threadId": "abc123xyz",
      "scheduledAt": "2025-03-15T09:00:00.000Z",
      "provider": "THREADS",
      "providerUserId": "12345678",
      "status": "READY",
      "posts": [
        {
          "id": "post_001",
          "content": "First post in the thread",
          "postOrder": 0,
          "images": [],
          "topic": "marketing",
          "status": "READY",
          "publishedAt": null,
          "permaLink": null,
          "autoRepostDelay": ["168"],
          "postMedia": [],
          "analytics": null,
          "spoilerRanges": [{ "offset": 0, "length": 5 }],
          "isSpoilerMedia": false
        }
      ]
    }
  ],
  "count": 1
}

Create Post

`POST /api/v1/posts`

Creates a new post or thread. Omit scheduleAt to save as a draft. Provide multiple items in the posts array to create a thread.Request Body:

providerId (required) — Provider ID from the /providers endpoint
posts (required) — Array of post objects (min 1):
- text (required) — Post content
- topic (optional) — Topic/category label
- media (optional) — Array of { url, altText? } objects with public image URLs
- spoilerRanges (optional, Threads only) — Array of { offset, length } objects marking character ranges in the post text as spoilers. offset is a 0-indexed character position; length is the number of characters. Max 10 ranges per post.
- isSpoilerMedia (optional, Threads only) — When true, all media attached to the post is marked as a spoiler. Ignored by non-Threads providers.
scheduleAt (optional) — Datetime string, e.g. 2025-03-15T09:00:00. Interpreted in your configured timezone unless a timezone offset is included.
autoRepost (optional) — Object with enabled (boolean) and delays (string array with exactly one delay value in hours, e.g. ["6"] for 6 hours). Only a single delay is supported.
teamId (optional) — Team ID

Request

curl -X POST https://blacktwist.app/api/v1/posts \
  -H "Authorization: Bearer bt_api_..." \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "clx....",
    "posts": [
      {
        "text": "First post in a thread",
        "topic": "marketing",
        "media": [
          { "url": "https://example.com/image.jpg", "altText": "A photo" }
        ],
        "spoilerRanges": [{ "offset": 0, "length": 5 }],
        "isSpoilerMedia": true
      },
      {
        "text": "Second post in the thread"
      }
    ],
    "scheduleAt": "2025-03-15T09:00:00",
    "autoRepost": {
      "enabled": true,
      "delays": ["6"]
    }
  }'

Response

{
  "threadId": "abc123xyz",
  "status": "scheduled",
  "scheduledAt": "2025-03-15T09:00:00.000Z",
  "postCount": 2,
  "autoPlugApplied": true
}

List Drafts

`GET /api/v1/posts/drafts`

Returns all draft threads (posts without a scheduled date).Query Parameters:

teamId (optional) — Team ID

Request

curl https://blacktwist.app/api/v1/posts/drafts \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "drafts": [
    {
      "threadId": "draft_abc123",
      "provider": "THREADS",
      "providerUserId": "12345678",
      "createdAt": "2025-03-10T14:00:00.000Z",
      "posts": [
        {
          "id": "post_d01",
          "content": "Draft post content",
          "postOrder": 0,
          "images": [],
          "topic": null,
          "postMedia": [],
          "spoilerRanges": [],
          "isSpoilerMedia": false
        }
      ]
    }
  ],
  "count": 1
}

Get Thread

`GET /api/v1/posts/:threadId`

Returns a single thread with all its posts and analytics.

Request

curl https://blacktwist.app/api/v1/posts/abc123xyz \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "thread": {
    "threadId": "abc123xyz",
    "scheduledAt": "2025-03-15T09:00:00.000Z",
    "provider": "THREADS",
    "providerUserId": "12345678",
    "status": "READY",
    "posts": [
      {
        "id": "post_001",
        "content": "First post in the thread",
        "postOrder": 0,
        "images": [],
        "topic": "marketing",
        "status": "READY",
        "publishedAt": null,
        "permaLink": null,
        "autoRepostDelay": [],
        "postMedia": [],
        "analytics": null,
        "spoilerRanges": [{ "offset": 0, "length": 5 }],
        "isSpoilerMedia": false
      }
    ]
  }
}

Delete Thread

`DELETE /api/v1/posts/:threadId`

Deletes a thread and all its posts, media, and associated data.

Request

curl -X DELETE https://blacktwist.app/api/v1/posts/abc123xyz \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "deleted": true,
  "threadId": "abc123xyz",
  "postsDeleted": 2
}

Edit Single Post

`PATCH /api/v1/posts/:threadId/posts/:postId`

Updates a single post within a thread. Only posts with status READY can be edited. Provide at least one field to update.Request Body:

content (optional) — New post text
topic (optional) — New topic (set to null to remove)
media (optional) — Array of { url, altText? } objects. Replaces all existing media.
spoilerRanges (optional, Threads only) — Array of { offset, length } objects. Replaces all existing spoiler ranges. Pass [] to clear them. Max 10 ranges.
isSpoilerMedia (optional, Threads only) — Toggles the media spoiler flag. Pass false to clear.

Request

curl -X PATCH https://blacktwist.app/api/v1/posts/abc123xyz/posts/post_001 \
  -H "Authorization: Bearer bt_api_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated post content",
    "topic": "growth",
    "spoilerRanges": [{ "offset": 0, "length": 7 }],
    "isSpoilerMedia": true
  }'

Response

{
  "postId": "post_001",
  "threadId": "abc123xyz",
  "updated": {
    "content": true,
    "topic": true,
    "media": false,
    "spoilerRanges": true,
    "isSpoilerMedia": true
  }
}

Edit Entire Thread

`PUT /api/v1/posts/:threadId/edit`

Replaces all posts in a thread. Include id for existing posts to update them. Omit id to create new posts. Posts not included in the array are deleted. All posts must have status READY.Request Body:

posts (required) — Array of post objects (min 1):
- id (optional) — Existing post ID to update
- text (required) — Post content
- topic (optional) — Topic label
- media (optional) — Array of { url, altText? } objects
- spoilerRanges (optional, Threads only) — Array of { offset, length } objects. Omitting clears any existing spoiler ranges on the post (this endpoint replaces all post state). Max 10 ranges.
- isSpoilerMedia (optional, Threads only) — Media spoiler flag. Omitting clears the flag.

Request

curl -X PUT https://blacktwist.app/api/v1/posts/abc123xyz/edit \
  -H "Authorization: Bearer bt_api_..." \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [
      {
        "id": "post_001",
        "text": "Updated first post",
        "spoilerRanges": [{ "offset": 0, "length": 7 }],
        "isSpoilerMedia": true
      },
      { "text": "Brand new second post", "topic": "growth" }
    ]
  }'

Response

{
  "threadId": "abc123xyz",
  "postsUpdated": 1,
  "postsCreated": 1,
  "postsDeleted": 0,
  "totalPosts": 2
}

Reschedule Thread

`PUT /api/v1/posts/:threadId/reschedule`

Changes the scheduled time for a thread. All posts in the thread must have status READY (not yet published).Request Body:

scheduleAt (required) — New datetime string, e.g. 2025-04-01T10:00:00

Request

curl -X PUT https://blacktwist.app/api/v1/posts/abc123xyz/reschedule \
  -H "Authorization: Bearer bt_api_..." \
  -H "Content-Type: application/json" \
  -d '{ "scheduleAt": "2025-04-01T10:00:00" }'

Response

{
  "threadId": "abc123xyz",
  "scheduledAt": "2025-04-01T10:00:00.000Z",
  "postsUpdated": 2
}

Providers

Analytics