Posts
Publish to Threads via API
A POST /posts with format feed publishes to the Threads account your customer connected. You don't build the Threads OAuth flow or store tokens: you send the content and Connect publishes it in the background. The same endpoint serves the other networks.
The request
POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"external_reference": "post-5120",
"format": "feed",
"caption": "We shipped v2 of the dashboard. What do you want to see in v3?",
"threads": {
"reply_control": "accounts_you_follow",
"topic_tag": "saas",
"first_comment": "Full changelog on our site."
}
}What you can do
- Publish plain text, with a caption of up to 500 characters.
- Publish up to 20 images or videos in a single post.
- Set who can reply with reply_control.
- Attach a link with preview to a text post with link_attachment.
- Tag the post with a topic_tag and publish a first_comment right after.
Rules and limits
- Threads only has the feed format. It needs a caption or media.
- link_attachment only works on a post without media. topic_tag does not accept periods or &.
- POST /posts responds 202 and publishing runs afterwards. Track it with GET /posts/{uuid}.
- external_reference is required. Sending the same reference again on the same account, while it is publishing or after it was published, returns 409.
- The Idempotency-Key header (up to 255 characters) returns the already stored post when the same request is repeated.
Main fields
| Field | Type | Required | Description |
|---|---|---|---|
| external_reference | string | Yes | The post's id in your system (up to 100 characters). Stops the same post from being published twice on the same account. |
| format | string | Yes | Always feed on Threads. |
| caption | string | No | The post text, up to 500 characters. Required when there is no media. |
| media | array | No | Up to 20 images or videos, in order. Leave it out for a text-only post. |
| threads.reply_control | string | No | Who can reply: everyone, accounts_you_follow, mentioned_only, parent_post_author_only or followers_only. |
| threads.link_attachment | string | No | A link with preview attached to the post. Only on a post without media. |
| threads.topic_tag | string | No | Topic tag, up to 50 characters, no periods and no &. |
| threads.first_comment | string | No | A reply posted by the account itself right after the post, up to 500 characters. |
Who it is for
Social media tool
Your own scheduling product sends the post to Threads alongside Instagram and LinkedIn, through the same endpoint.
AI agent that publishes
An agent writes the text and publishes it to the customer's Threads, picking reply_control to limit replies.
CRM with content
A CRM publishes customer news to Threads and uses first_comment to place the link right below it.
Works with
Threads
Frequently asked questions
Can I publish text only to Threads?
Yes. Send format feed and caption, without media. The caption goes up to 500 characters.
How many media items fit in a Threads post?
Up to 20 images or videos in one post.
How do I know the post went out?
POST /posts responds 202 with the post in created. Poll GET /posts/{uuid} until status is published or failed.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
