{
  "info": {
    "_postman_id": "blacktwist-api-v1",
    "name": "BlackTwist API",
    "description": "REST API for BlackTwist — a social media management tool for Threads, Bluesky, and other platforms. All endpoints require Bearer token authentication using your API key.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{apiKey}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://blacktwist.app",
      "type": "string"
    },
    {
      "key": "apiKey",
      "value": "",
      "type": "string",
      "description": "Your BlackTwist API key"
    }
  ],
  "item": [
    {
      "name": "Providers",
      "description": "Manage connected social media provider accounts.",
      "item": [
        {
          "name": "List Providers",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/providers?teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "providers"],
              "query": [
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Use \"personal\" for personal account or omit for all accessible providers."
                }
              ]
            },
            "description": "Returns all connected social media provider accounts for the authenticated user. Optionally scoped to a specific team."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Posts",
      "description": "Create, read, update, and delete scheduled and published posts (threads).",
      "item": [
        {
          "name": "List Posts",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/posts?from=2026-03-01T00:00:00&to=2026-03-31T23:59:59&providerId=clxxxxxxxxxxxxxxx&teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "posts"],
              "query": [
                {
                  "key": "from",
                  "value": "2026-03-01T00:00:00",
                  "description": "Start of date range (ISO 8601). Required."
                },
                {
                  "key": "to",
                  "value": "2026-03-31T23:59:59",
                  "description": "End of date range (ISO 8601). Required."
                },
                {
                  "key": "providerId",
                  "value": "clxxxxxxxxxxxxxxx",
                  "description": "Filter by provider account ID. Optional."
                },
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Optional."
                }
              ]
            },
            "description": "Returns all posts (threads) within the given date range. Both `from` and `to` are required."
          },
          "response": []
        },
        {
          "name": "Create Post",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"providerId\": \"clxxxxxxxxxxxxxxx\",\n  \"posts\": [\n    {\n      \"text\": \"This is the first post in the thread.\",\n      \"topic\": \"tech\",\n      \"media\": [\n        {\n          \"url\": \"https://example.com/image.jpg\",\n          \"altText\": \"A descriptive alt text for the image\"\n        }\n      ]\n    },\n    {\n      \"text\": \"This is a follow-up post in the same thread.\"\n    }\n  ],\n  \"scheduleAt\": \"2026-04-10T09:00:00Z\",\n  \"autoRepost\": {\n    \"enabled\": true,\n    \"delays\": [\"6\"]\n  },\n  \"teamId\": \"personal\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/posts",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "posts"]
            },
            "description": "Creates a new thread (one or more posts). If `scheduleAt` is omitted the post is saved as a draft. `autoRepost.delays` are in hours (e.g. 168 = 7 days, 336 = 14 days, 720 = 30 days)."
          },
          "response": []
        },
        {
          "name": "List Drafts",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/posts/drafts?teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "posts", "drafts"],
              "query": [
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Optional."
                }
              ]
            },
            "description": "Returns all draft threads for the authenticated user."
          },
          "response": []
        },
        {
          "name": "Get Thread",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/posts/thread_abc123",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "posts", "thread_abc123"]
            },
            "description": "Returns details for a single thread including all its posts."
          },
          "response": []
        },
        {
          "name": "Delete Thread",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/posts/thread_abc123",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "posts", "thread_abc123"]
            },
            "description": "Deletes a thread and all its associated posts. This action is irreversible."
          },
          "response": []
        },
        {
          "name": "Edit Thread",
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"posts\": [\n    {\n      \"id\": \"post_xyz789\",\n      \"text\": \"Updated text for the first post.\",\n      \"topic\": \"tech\",\n      \"media\": [\n        {\n          \"url\": \"https://example.com/updated-image.jpg\",\n          \"altText\": \"Updated alt text\"\n        }\n      ]\n    },\n    {\n      \"text\": \"A new second post added to the thread.\"\n    }\n  ]\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/posts/thread_abc123/edit",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "posts", "thread_abc123", "edit"]
            },
            "description": "Replaces all posts in a thread. Include `id` for existing posts to update them; omit `id` to add new posts. At least one post is required."
          },
          "response": []
        },
        {
          "name": "Reschedule Thread",
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"scheduleAt\": \"2026-04-15T14:00:00Z\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/posts/thread_abc123/reschedule",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "posts", "thread_abc123", "reschedule"]
            },
            "description": "Updates the scheduled publish time for a thread. `scheduleAt` must be an ISO 8601 datetime string."
          },
          "response": []
        },
        {
          "name": "Edit Post (single)",
          "request": {
            "method": "PATCH",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"content\": \"Updated content for this individual post.\",\n  \"topic\": \"marketing\",\n  \"media\": [\n    {\n      \"url\": \"https://example.com/new-image.png\",\n      \"altText\": \"New image alt text\"\n    }\n  ]\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/posts/thread_abc123/posts/post_xyz789",
              "host": ["{{baseUrl}}"],
              "path": [
                "api",
                "v1",
                "posts",
                "thread_abc123",
                "posts",
                "post_xyz789"
              ]
            },
            "description": "Partially updates a single post within a thread. All fields are optional — only provided fields are updated."
          },
          "response": []
        },
        {
          "name": "Get Thread Follow-Up",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/posts/thread_abc123/follow-up",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "posts", "thread_abc123", "follow-up"]
            },
            "description": "Returns the follow-up (auto-plug) configuration attached to a thread."
          },
          "response": []
        },
        {
          "name": "Set Thread Follow-Up",
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"isEnabled\": true,\n  \"text\": \"If you found this useful, check out my newsletter at example.com!\",\n  \"media\": [\n    {\n      \"url\": \"https://example.com/promo-image.jpg\",\n      \"altText\": \"Newsletter promo banner\"\n    }\n  ],\n  \"delayTimeMinutes\": 60,\n  \"delayTimeMinutesEnabled\": true,\n  \"numberOfLikes\": 50,\n  \"numberOfLikesEnabled\": true,\n  \"numberOfReplies\": 10,\n  \"numberOfRepliesEnabled\": false,\n  \"numberOfReposts\": 5,\n  \"numberOfRepostsEnabled\": false\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/posts/thread_abc123/follow-up",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "posts", "thread_abc123", "follow-up"]
            },
            "description": "Creates or updates the follow-up (auto-plug) reply for a thread. The follow-up fires when enabled conditions are met (time delay, like count, reply count, or repost count). Set `isEnabled: false` to disable without losing the configuration."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Analytics",
      "description": "Access engagement metrics, time-series data, post performance, follower growth, consistency scores, daily recaps, and content recommendations.",
      "item": [
        {
          "name": "Get Live Metrics",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/analytics/metrics?providerUserId=12345678901234567&from=2026-03-01T00:00:00&to=2026-03-31T23:59:59&teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "analytics", "metrics"],
              "query": [
                {
                  "key": "providerUserId",
                  "value": "12345678901234567",
                  "description": "The user's ID on the social platform. Required."
                },
                {
                  "key": "from",
                  "value": "2026-03-01T00:00:00",
                  "description": "Start of date range (ISO 8601). Optional."
                },
                {
                  "key": "to",
                  "value": "2026-03-31T23:59:59",
                  "description": "End of date range (ISO 8601). Optional."
                },
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Optional."
                }
              ]
            },
            "description": "Returns aggregate engagement metrics (likes, replies, reposts, views, followers, etc.) for the specified provider account and date range."
          },
          "response": []
        },
        {
          "name": "Get Metric Timeseries",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/analytics/timeseries?providerUserId=12345678901234567&metric=LIKES&from=2026-03-01T00:00:00&to=2026-03-31T23:59:59&teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "analytics", "timeseries"],
              "query": [
                {
                  "key": "providerUserId",
                  "value": "12345678901234567",
                  "description": "The user's ID on the social platform. Required."
                },
                {
                  "key": "metric",
                  "value": "LIKES",
                  "description": "Metric to chart. Required. Enum values: LIKES, REPLIES, REPOSTS, VIEWS, FOLLOWERS, QUOTES."
                },
                {
                  "key": "from",
                  "value": "2026-03-01T00:00:00",
                  "description": "Start of date range (ISO 8601). Required."
                },
                {
                  "key": "to",
                  "value": "2026-03-31T23:59:59",
                  "description": "End of date range (ISO 8601). Required."
                },
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Optional."
                }
              ]
            },
            "description": "Returns a day-by-day time series for a single metric. Useful for charting trends over time."
          },
          "response": []
        },
        {
          "name": "Get Post Analytics",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/analytics/posts?providerUserId=12345678901234567&from=2026-03-01T00:00:00&to=2026-03-31T23:59:59&teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "analytics", "posts"],
              "query": [
                {
                  "key": "providerUserId",
                  "value": "12345678901234567",
                  "description": "The user's ID on the social platform. Required."
                },
                {
                  "key": "from",
                  "value": "2026-03-01T00:00:00",
                  "description": "Start of date range (ISO 8601). Required."
                },
                {
                  "key": "to",
                  "value": "2026-03-31T23:59:59",
                  "description": "End of date range (ISO 8601). Required."
                },
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Optional."
                }
              ]
            },
            "description": "Returns per-post engagement analytics (likes, replies, reposts, views) for all posts published within the date range."
          },
          "response": []
        },
        {
          "name": "Get Follower Growth",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/analytics/followers?providerUserId=12345678901234567&from=2026-03-01T00:00:00&to=2026-03-31T23:59:59&teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "analytics", "followers"],
              "query": [
                {
                  "key": "providerUserId",
                  "value": "12345678901234567",
                  "description": "The user's ID on the social platform. Required."
                },
                {
                  "key": "from",
                  "value": "2026-03-01T00:00:00",
                  "description": "Start of date range (ISO 8601). Required."
                },
                {
                  "key": "to",
                  "value": "2026-03-31T23:59:59",
                  "description": "End of date range (ISO 8601). Required."
                },
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Optional."
                }
              ]
            },
            "description": "Returns daily follower count snapshots to track audience growth over the selected period."
          },
          "response": []
        },
        {
          "name": "Get Consistency Score",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/analytics/consistency?providerUserId=12345678901234567&teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "analytics", "consistency"],
              "query": [
                {
                  "key": "providerUserId",
                  "value": "12345678901234567",
                  "description": "The user's ID on the social platform. Required."
                },
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Optional."
                }
              ]
            },
            "description": "Returns posting consistency data including streaks, posting frequency, and consistency score."
          },
          "response": []
        },
        {
          "name": "Get Daily Recap",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/analytics/daily-recap?providerUserId=12345678901234567&teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "analytics", "daily-recap"],
              "query": [
                {
                  "key": "providerUserId",
                  "value": "12345678901234567",
                  "description": "The user's ID on the social platform. Required."
                },
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Optional."
                }
              ]
            },
            "description": "Returns a daily recap summary of engagement activity for the provider account."
          },
          "response": []
        },
        {
          "name": "Get Recommendations",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/analytics/recommendations?providerUserId=12345678901234567&teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "analytics", "recommendations"],
              "query": [
                {
                  "key": "providerUserId",
                  "value": "12345678901234567",
                  "description": "The user's ID on the social platform. Required."
                },
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Optional."
                }
              ]
            },
            "description": "Returns AI-powered content and posting time recommendations based on historical performance data."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Follow-Ups",
      "description": "Manage follow-up (auto-plug) templates used as defaults when creating new posts.",
      "item": [
        {
          "name": "Get Follow-Up Templates",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/follow-up/templates?userProviderId=clxxxxxxxxxxxxxxx&teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "follow-up", "templates"],
              "query": [
                {
                  "key": "userProviderId",
                  "value": "clxxxxxxxxxxxxxxx",
                  "description": "The provider account ID (not the platform user ID). Required."
                },
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Optional."
                }
              ]
            },
            "description": "Returns default follow-up templates configured for the given provider account. These templates are copied when creating per-thread follow-ups."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Time Slots",
      "description": "Manage scheduled posting time slots for auto-scheduling content.",
      "item": [
        {
          "name": "List Time Slots",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/time-slots?providerId=clxxxxxxxxxxxxxxx&teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "time-slots"],
              "query": [
                {
                  "key": "providerId",
                  "value": "clxxxxxxxxxxxxxxx",
                  "description": "The provider account ID to fetch time slots for. Required."
                },
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Optional."
                }
              ]
            },
            "description": "Returns the configured posting time slots for a provider account. Time slots define when auto-scheduled posts are published."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Subscription",
      "description": "Retrieve subscription and billing information.",
      "item": [
        {
          "name": "Get Subscription",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/subscription?teamId=personal",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "subscription"],
              "query": [
                {
                  "key": "teamId",
                  "value": "personal",
                  "description": "Team ID. Optional."
                }
              ]
            },
            "description": "Returns the current subscription plan, status, and billing details for the authenticated user or team."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Settings",
      "description": "Access user account settings.",
      "item": [
        {
          "name": "Get Settings",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/settings",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "settings"]
            },
            "description": "Returns user settings including notification preferences, timezone, date format, auto-repost configuration, and reminder settings."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Teams",
      "description": "List teams the authenticated user belongs to.",
      "item": [
        {
          "name": "List Teams",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/v1/teams",
              "host": ["{{baseUrl}}"],
              "path": ["api", "v1", "teams"]
            },
            "description": "Returns all teams the authenticated user is a member of. The `teamId` returned here can be used as the `teamId` parameter in other endpoints."
          },
          "response": []
        }
      ]
    }
  ]
}