openapi: 3.0.0 info: title: Threads API description: >- The Threads API enables developers to build their own unique integrations, and helps creators and brands manage their Threads presence at scale and easily share inspiring content with their communities. version: 1.0.0 servers: - url: http://{{api_host}} components: securitySchemes: noauthAuth: type: http scheme: noauth oauth2Auth: type: http scheme: oauth2 security: - oauth2Auth: [] tags: - name: Authorization description: >- Authorization is a required step to get the necessary user permissions to act on behalf of the user. Please take a look at the [walkthrough of the authentication process](https://developers.facebook.com/docs/threads/get-started/get-access-tokens-and-permissions). Once the access token is retrieved, use the [access token debugger](https://developers.facebook.com/tools/debug/accesstoken) to check if the access token has the correct permissions (including `threads_basic`, `threads_content_publish`, `threads_read_replies`, `threads_manage_replies`, `threads_manage_insights`) and verify that the access token hasn't expired. Follow the [documentation](https://developers.facebook.com/docs/threads/get-started/long-lived-tokens) to exchange a short-lived Threads User Access Token for a long-lived token and refresh unexpired long-lived Threads User Access tokens. **Note:** The `threads_basic` permission is sufficient for the exchange or refresh process. - name: Post to Threads description: >- This folder will enable you to use the Threads API to publish single image, video, text or carousel posts. - name: Post to Threads > Single Threads Posts description: >- This folder will enable you to: 1. Create a Media Container of text/image/video type. The API will return a Media Container ID which will be used in the second step. 2. Publish a single Threads post. - name: Post to Threads > Carousel Threads Posts description: >- This folder will enable you to: 1. Create an Item Container for each image or video that will appear in a Carousel. 2. Create a Carousel Container. 3. Publish a Carousel post. - name: Post to Threads > Quote Threads Posts description: >- This folder will enable you to: 1. Create a Media Container. The API will return a Media Container ID which will be used in the second step. 2. Publish a single Quote post. - name: Post to Threads > Repost Threads Posts description: This folder will enable you to repost an original Threads post. - name: Read And Manage Threads description: >- This folder will enable you to use the Threads API to retrieve details about profiles and media objects, reads insights and handle reply moderation. - name: Read And Manage Threads > Retrieve Threads Profiles description: >- This folder will enable you to get profile information about a Threads user. - name: Read And Manage Threads > Retrieve Threads Media Objects description: >- This folder will enable you to use the Threads API to retrieve details about posts. - name: Read And Manage Threads > Read Threads Insights description: >- This folder will enable you to use the Threads API to retrieve details about posts and accounts. - name: Read And Manage Threads > Read and Manage Threads Replies description: >- The Threads Reply Moderation API allows you to read and manage replies to users' own Threads. - name: Read And Manage Threads > Read Replies Media Objects description: >- This folder will enable you to use the Threads API to retrieve details about a user's own replies. - name: Troubleshooting description: This folder will enbale you to perform basic toubleshooting. paths: /oauth/access_token: post: tags: - Authorization summary: Exchange the Code For a Token description: >- Once you receive a code, exchange it for a short-lived access token by sending a `POST` request to the /oauth/access_token [endpoint](https://developers.facebook.com/docs/threads/get-started/get-access-tokens-and-permissions#step-2--exchange-the-code-for-a-token) requestBody: content: application/x-www-form-urlencoded: schema: properties: {} security: - noauthAuth: [] parameters: - name: client_id in: query schema: type: string description: >- Your Threads App ID displayed in App Dashboard > App settings > Basic > Threads App ID. Example: 990602627938098. example: '{{app_id}}' - name: client_secret in: query schema: type: string description: >- Your Threads App Secret displayed in App Dashboard > App settings > Basic > Threads App secret. Example: a1b2C3D4. example: '{{app_secret}}' - name: code in: query schema: type: string description: Authorization Code example: '{{code}}' - name: grant_type in: query schema: type: string description: This value is required example: authorization_code - name: redirect_uri in: query schema: type: string description: >- The redirect URI you passed when you directed the user to the Authorization Window. This must be the same URI or the request will be rejected. example: '{{redirect_uri}}' responses: undefined: headers: Content-Type: schema: type: string example: application/json content: application/json: schema: type: object example: access_token: string user_id: string /access_token: get: tags: - Authorization summary: Get Long-Lived Access Token description: >- Use the `GET` /access_token [endpoint](https://developers.facebook.com/docs/threads/get-started/long-lived-tokens#get-a-long-lived-token) to exchange a short-lived Threads user access token for a long-lived token. parameters: - name: grant_type in: query schema: type: string example: th_exchange_token - name: client_secret in: query schema: type: string example: '{{app_secret}}' responses: undefined: headers: Content-Type: schema: type: string example: application/json content: application/json: schema: type: object example: access_token: string token_type: bearer expires_in: 5184000 /me/threads: post: tags: - Read And Manage Threads > Read and Manage Threads Replies summary: Control Who Can Reply description: >- Use the [reply_control](https://developers.facebook.com/docs/threads/reply-management#control-who-can-reply) parameter to specify who can reply to a post being created for publishing. requestBody: content: {} parameters: - name: media_type in: query schema: type: string example: '{{media_type}}' - name: text in: query schema: type: string example: Text - name: reply_control in: query schema: type: string example: '{{reply_control}}' responses: undefined: content: text/plain: schema: type: string example: |- { "id": "string" } get: tags: - Read And Manage Threads > Retrieve Threads Media Objects summary: Get a List of All a User's Threads description: >- Use the `GET` /{threads-user-id}/threads [endpoint](https://developers.facebook.com/docs/threads/threads-media#retrieve-a-list-of-all-a-user-s-threads) to return a paginated list of all threads created by a user. parameters: - name: fields in: query schema: type: string description: >- id (default): The media's ID. media_product_type: Surface where the media is published. In the case of Threads, the value is THREADS. media_type: The media type for a Threads post will be one of these values: TEXT_POST, IMAGE, VIDEO, CAROUSEL_ALBUM, AUDIO, or REPOST_FACADE. media_url: The posts media URL. permalink: Permanent link to the post. Will be omitted if the media contains copyrighted material or has been flagged for a copyright violation. owner: Instagram user ID who created the post. username: Instagram username who created the post. text: Represents text for a Threads post. timestamp: Post time. The publish date in ISO 8601 format. shortcode: Shortcode of the media. thumbnail_url: URL of thumbnail. This only shows up for Threads media with video. children: List of child posts. This only shows up for carousel posts. is_quote_post: Indicates if the media is a quoted post made by another user. example: '{{fields_threads}}' - name: limit in: query schema: type: integer description: >- Query string parameter representing the maximum number of media objects or records to return example: '50' responses: undefined: headers: Content-Type: schema: type: string example: application/json content: application/json: schema: type: object example: data: - id: string media_product_type: THREADS media_type: TEXT_POST permalink: string owner: id: string username: string text: This is a test post timestamp: 2024-09-12T23:17:39+0000 shortcode: string is_quote_post: false has_replies: false paging: cursors: before: string after: string /me/threads_publish: post: tags: - Post to Threads > Quote Threads Posts summary: Publish Threads Quote Post description: >- Use the `POST` /{threads-user-id}/threads_publish [endpoint](https://developers.facebook.com/docs/threads/posts#step-2--publish-a-threads-media-container) to publish the container ID returned in the previous step. requestBody: content: {} parameters: - name: creation_id in: query schema: type: string description: >- Identifier of the Threads media container created from the /threads endpoint. example: '{{container_id}}' responses: undefined: headers: Content-Type: schema: type: string example: application/json content: application/json: schema: type: object example: id: string /{thread_id}/repost: post: tags: - Post to Threads > Repost Threads Posts summary: Repost Threads Post description: >- Use the `POST` /{threads-user-id}/threads_publish [endpoint](https://developers.facebook.com/docs/threads/posts#step-2--publish-a-threads-media-container) to publish the container ID returned in the previous step. requestBody: content: {} parameters: - name: thread_id in: path schema: type: string required: true responses: undefined: headers: Content-Type: schema: type: string example: application/json content: application/json: schema: type: object example: id: string /me: get: tags: - Read And Manage Threads > Retrieve Threads Profiles summary: Get Threads User's Profile Information description: >- Use the `GET` /{threads-user-id}?fields=id,username,... [endpoint](https://developers.facebook.com/docs/threads/threads-profiles#retrieve-a-threads-user-s-profile-information) to return profile information about a Threads user. parameters: - name: fields in: query schema: type: string description: >- id: Threads user ID. This is returned by default. username: Handle or unique username on Threads. This is the same as the username on Instagram. threads_profile_picture_url: URL of the user's profile picture on Threads. threads_biography: Biography text on Threads profile. example: '{{fields_profile}}' responses: undefined: headers: Content-Type: schema: type: string example: application/json content: application/json: schema: type: object example: id: string username: string name: string threads_profile_picture_url: string threads_biography: string /{thread_id}: get: tags: - Read And Manage Threads > Retrieve Threads Media Objects summary: Get Threads Post Details description: >- Use the `GET` /{threads-media-id} [endpoint](https://developers.facebook.com/docs/threads/threads-media#retrieve-a-single-threads-media-object) to return an individual Threads media object. parameters: - name: fields in: query schema: type: string description: >- id (default): The media's ID. media_product_type: Surface where the media is published. In the case of Threads, the value is THREADS. media_type: The media type for a Threads post will be one of these values: TEXT_POST, IMAGE, VIDEO, CAROUSEL_ALBUM, AUDIO, or REPOST_FACADE. media_url: The posts media URL. permalink: Permanent link to the post. Will be omitted if the media contains copyrighted material or has been flagged for a copyright violation. owner: Instagram user ID who created the post. username: Instagram username who created the post. text: Represents text for a Threads post. timestamp: Post time. The publish date in ISO 8601 format. shortcode: Shortcode of the media. thumbnail_url: URL of thumbnail. This only shows up for Threads media with video. children: List of child posts. This only shows up for carousel posts. is_quote_post: Indicates if the media is a quoted post made by another user. example: '{{fields_threads}}' - name: thread_id in: path schema: type: string required: true responses: undefined: headers: Content-Type: schema: type: string example: application/json content: application/json: schema: type: object example: id: string media_product_type: THREADS media_type: TEXT_POST permalink: string owner: id: string username: string text: This is a test post timestamp: 2024-09-12T23:17:39+0000 shortcode: string is_quote_post: false has_replies: false /{thread_id}/insights: get: tags: - Read And Manage Threads > Read Threads Insights summary: Get Post Insights description: >- Use the `GET` /{threads-media-id}/insights [endpoint](https://developers.facebook.com/docs/threads/insights#media-insights) to return the insights of a given Threads post. parameters: - name: metric in: query schema: type: string description: |- views: The number of times the post was viewed. Note: This metric is in development. likes: The number of likes on the post. replies: The number of replies on the post. Note: This number includes only top-level replies. reposts: The number of times the post was reposted. quotes: The number of times the post was quoted. example: '{{metrics_post}}' - name: thread_id in: path schema: type: string required: true responses: undefined: content: text/plain: schema: type: string example: |- { "data": [ { "name": "views", "period": "lifetime", "values": [ { "value": 0 } ], "title": "Views", "description": "The number of times your post was viewed. This metric is in development (https://www.facebook.com/business/help/metrics-labeling)", "id": "{thread_id}/insights/views/lifetime" }, { "name": "likes", "period": "lifetime", "values": [ { "value": 0 } ], "title": "Likes", "description": "The number of likes on your post.", "id": "{thread_id}/insights/likes/lifetime" }, { "name": "replies", "period": "lifetime", "values": [ { "value": 0 } ], "title": "Replies", "description": "The number of replies on your post.", "id": "{thread_id}/insights/thread_replies/lifetime" }, { "name": "reposts", "period": "lifetime", "values": [ { "value": 0 } ], "title": "Reposts", "description": "The number of times your post was reposted.", "id": "{thread_id}/insights/reposts/lifetime" }, { "name": "quotes", "period": "lifetime", "values": [ { "value": 0 } ], "title": "Quotes", "description": "The number of times your post was quoted.", "id": "{thread_id}/insights/quotes/lifetime" } ] } /me/threads_insights: get: tags: - Read And Manage Threads > Read Threads Insights summary: Get Account Insights description: >- Use the `GET` /{threads-user-id}/threads_insights [endpoint](https://developers.facebook.com/docs/threads/insights#user-insights) to return the insights of a given Threads user. parameters: - name: metric in: query schema: type: string description: >- views: The number of times the post was viewed. Note: This metric is in development. likes: The number of likes on the post. replies: The number of replies on the post. Note: This number includes only top-level replies. reposts: The number of times the post was reposted. quotes: The number of times the post was quoted. reposts: The number of times your posts were quoted. followers_count: Your total number of followers on Threads. follower_demographics: The demographic characteristics of followers, including countries, cities and gender distribution. Note: Does not support the since and until parameters. example: '{{metrics_account}}' responses: undefined: content: text/plain: schema: type: string example: |- { "data": [ { "name": "views", "period": "day", "values": [ { "value": 0, "end_time": "2024-09-16T07:00:00+0000" }, { "value": 0, "end_time": "2024-09-17T07:00:00+0000" } ], "title": "views", "description": "The number of times your profile was viewed.", "id": "{user_id}/insights/views/day" }, { "name": "likes", "period": "day", "title": "likes", "description": "The number of likes on your posts.", "total_value": { "value": 0 }, "id": "{user_id}/insights/likes/day" }, { "name": "replies", "period": "day", "title": "replies", "description": "The number of replies on your posts.", "total_value": { "value": 0 }, "id": "{user_id}/insights/replies/day" }, { "name": "reposts", "period": "day", "title": "reposts", "description": "The number of times your posts were reposted.", "total_value": { "value": 0 }, "id": "{user_id}/insights/reposts/day" }, { "name": "quotes", "period": "day", "title": "quotes", "description": "The number of times your posts were quoted.", "total_value": { "value": 0 }, "id": "{user_id}/insights/quotes/day" }, { "name": "followers_count", "period": "day", "title": "followers_count", "description": "This is your total number of followers on Threads.", "total_value": { "value": 0 }, "id": "{user_id}/insights/followers_count/day" } ], "paging": { "previous": "string", "next": "string" } } /{thread_id}/replies: get: tags: - Read And Manage Threads > Read and Manage Threads Replies summary: Get Threads Replies description: >- Use `GET` /replies [endpoint](https://developers.facebook.com/docs/threads/reply-management#replies) to fetch a paginated list of all top-level replies. parameters: - name: fields in: query schema: type: string description: >- id (default): The media's ID. text: Represents text for a Threads reply. This is optional on image, video, and carousel replies. username: Instagram username who created the post. Note: This only works for public users, your own user, and users that you follow. permalink: Permanent link to the post. Will be omitted if the media contains copyrighted material or has been flagged for a copyright violation. Note: This only works for public users, your own user, and users that you follow. timestamp: The publish date and time of the post in ISO 8601 format. media_product_type: Surface where the media is published. In the case of Threads, the value is THREADS. media_type: The media type for a Threads reply. Values: TEXT_POST, IMAGE, VIDEO, CAROUSEL_ALBUM media_url: The posts media URL. This only shows for image, video, and carousel replies. shortcode: Shortcode of the media. thumbnail_url: URL of thumbnail. This only shows for Threads replies with video. children: List of child posts. This only shows for carousel replies. has_replies: true if the Threads post or reply has replies that you can see. root_post: Media ID of the top-level post or original thread in the reply tree. Note: This only appears on replies. replied_to: Media ID of the immediate parent of the reply. Note: This only appears on replies. is_reply: true if the Threads media is a reply. false if the Threads media is a top-level post. hide_status: Whether or not the reply is hidden. Values: NOT_HUSHED, UNHUSHED, HIDDEN example: text - name: reverse in: query schema: type: boolean example: 'false' - name: thread_id in: path schema: type: string required: true responses: undefined: headers: Content-Type: schema: type: string example: application/json content: application/json: schema: type: object example: data: - id: string text: reply timestamp: 2024-09-17T20:54:47+0000 media_product_type: THREADS media_type: TEXT_POST permalink: string shortcode: string username: string is_quote_post: false has_replies: false is_reply: true is_reply_owned_by_me: false root_post: id: string replied_to: id: string paging: cursors: before: string after: string /{thread_id}/conversation: get: tags: - Read And Manage Threads > Read and Manage Threads Replies summary: Get Threads Conversations description: >- Use `GET` /conversation [endpoint](https://developers.facebook.com/docs/threads/reply-management#conversations) to fetch a paginated and flattened list of all top-level and nested replies. parameters: - name: fields in: query schema: type: string description: >- id (default): The media's ID. text: Represents text for a Threads reply. This is optional on image, video, and carousel replies. username: Instagram username who created the post. Note: This only works for public users, your own user, and users that you follow. permalink: Permanent link to the post. Will be omitted if the media contains copyrighted material or has been flagged for a copyright violation. Note: This only works for public users, your own user, and users that you follow. timestamp: The publish date and time of the post in ISO 8601 format. media_product_type: Surface where the media is published. In the case of Threads, the value is THREADS. media_type: The media type for a Threads reply.Values: TEXT_POST, IMAGE, VIDEO, CAROUSEL_ALBUM media_url: The posts media URL. This only shows for image, video, and carousel replies. shortcode: Shortcode of the media. thumbnail_url: URL of thumbnail. This only shows for Threads replies with video. children: List of child posts. This only shows for carousel replies. has_replies: true if the Threads post or reply has replies that you can see. root_post: Media ID of the top-level post or original thread in the reply tree. Note: This only appears on replies. replied_to: Media ID of the immediate parent of the reply. Note: This only appears on replies. is_reply: true if the Threads media is a reply. false if the Threads media is a top-level post. hide_status: Whether or not the reply is hidden. Values: NOT_HUSHED, UNHUSHED, HIDDEN example: '{{fields_replies}}' - name: reverse in: query schema: type: boolean example: 'false' - name: thread_id in: path schema: type: string required: true responses: undefined: headers: Content-Type: schema: type: string example: application/json content: application/json: schema: type: object example: data: - id: string text: reply timestamp: 2024-09-17T20:54:47+0000 media_product_type: THREADS media_type: TEXT_POST permalink: string shortcode: string username: string is_quote_post: false has_replies: false is_reply: true is_reply_owned_by_me: false root_post: id: string replied_to: id: string paging: cursors: before: string after: string /{reply_thread_id}/manage_reply: post: tags: - Read And Manage Threads > Read and Manage Threads Replies summary: Hide Replies description: >- Use `POST` /manage_reply [endpoint](https://developers.facebook.com/docs/threads/reply-management#hide-replies) to hide/unhide any top-level replies. requestBody: content: {} parameters: - name: hide in: query schema: type: boolean example: 'true' - name: reply_thread_id in: path schema: type: string required: true responses: undefined: headers: Content-Type: schema: type: string example: application/json content: application/json: schema: type: object example: success: true /me/replies: get: tags: - Read And Manage Threads > Read Replies Media Objects summary: Get a List of All a User's Replies description: >- Use the `GET` /{threads-user-id}/threads [endpoint](https://developers.facebook.com/docs/threads/threads-media#retrieve-a-list-of-all-a-user-s-threads) to return a paginated list of all threads created by a user. parameters: - name: fields in: query schema: type: string description: >- id (default): The media's ID. media_product_type: Surface where the media is published. In the case of Threads, the value is THREADS. media_type: The media type for a Threads post will be one of these values: TEXT_POST, IMAGE, VIDEO, CAROUSEL_ALBUM, AUDIO, or REPOST_FACADE. media_url: The posts media URL. permalink: Permanent link to the post. Will be omitted if the media contains copyrighted material or has been flagged for a copyright violation. owner: Instagram user ID who created the post. username: Instagram username who created the post. text: Represents text for a Threads post. timestamp: Post time. The publish date in ISO 8601 format. shortcode: Shortcode of the media. thumbnail_url: URL of thumbnail. This only shows up for Threads media with video. children: List of child posts. This only shows up for carousel posts. is_quote_post: Indicates if the media is a quoted post made by another user. example: '{{fields_replies}}' - name: limit in: query schema: type: integer description: >- Query string parameter representing the maximum number of media objects or records to return example: '50' responses: undefined: headers: Content-Type: schema: type: string example: application/json content: application/json: schema: type: object example: data: - id: string media_product_type: THREADS media_type: TEXT_POST permalink: string username: string text: REPLY timestamp: 2024-09-12T23:11:55+0000 shortcode: string is_quote_post: false has_replies: false paging: cursors: before: string after: string /{container_id}/: get: tags: - Troubleshooting summary: Check Container's Publishing Status description: >- Use `POST` /{threads-user-id}/threads_publish [endpoint](https://developers.facebook.com/docs/threads/troubleshooting#publishing-does-not-return-a-media-id) to check a container's publishing status. parameters: - name: fields in: query schema: type: string description: > EXPIRED The container was not published within 24 hours and has expired. ERROR The container failed to complete the publishing process. FINISHED The container and its media object are ready to be published. IN_PROGRESS The container is still in the publishing process. PUBLISHED The container's media object has been published. example: '{{fields_container}}' - name: container_id in: path schema: type: string required: true responses: undefined: content: text/plain: schema: type: string example: |- { "id": "string", "status": "FINISHED" } /me/threads_publishing_limit: get: tags: - Troubleshooting summary: Retrieve Publishing Quota Limit description: >- Use `GET` /threads_publishing_limit [endpoint](https://developers.facebook.com/docs/threads/troubleshooting#retrieve-publishing-quota-limit) to check a user's publishing API quota limit. parameters: - name: fields in: query schema: type: string description: user's current Threads API usage total. example: '{{fields_quota}}' responses: undefined: content: text/plain: schema: type: string example: |- { "data": [ { "quota_usage": 1, "config": { "quota_total": 250, "quota_duration": 86400 }, "reply_quota_usage": 0, "reply_config": { "quota_total": 1000, "quota_duration": 86400 } } ] }