Threads API

Spoilers

You can create posts with spoilers using the Threads API. Spoilers can be added to text in a post or can be used with media types like images and videos.

This document covers:

Limitations

  • Media spoilers only work with a media_type of IMAGE, VIDEO or CAROUSEL.
  • The maximum number of text spoiler entities per post is limited to 10.

Text and Media Spoilers

Create a spoiler within a text field

To create a text post with a spoiler, use the text_entities parameter. This parameter takes in a list of entity_type, offset, and length values. Each entry represents part of the text post where the spoiler will be applied.

Parameters

NameDescription

entity_type

string

Indicates the kind of entity_type.

Values: SPOILER, spoiler

offset

int

The starting position of the spoiler.

Values: Positive whole numbers (0, 1, 2, etc.)

length

int

The length of the spoiler text starting from the offset position.

Values: Positive whole numbers (1, 2, etc.)

Create a media spoiler

To create a post with spoilers for media objects (i.e., image, video), use the is_spoiler_media parameter.

Parameters

NameDescription

is_spoiler_media

Boolean

Indicates if the media should be a spoiler or not.

Values: true, false

Single Threads Posts

Step 1: Create a media container

Spoilers for single Threads posts need to be provided during the media container creation phase.

  • If a spoiler needs to be added in the text field of the post, use the text_entities parameter.
  • If a spoiler needs to be added to the media object in the post, use the is_spoiler_media parameter.
  • If a spoiler needs to be added to the text and media objects in the post, use both the text_entities and is_spoiler_media parameters.

Example requests

Spoiler only in the text field
curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "media_type=TEXT" \
  -d "text=<TEXT>" \
  -d "text_entities=[
    {
      "entity_type": "SPOILER",
      "offset": 0,
      "length": 2
    },
    {
      "entity_type": "SPOILER",
      "offset": 2,
      "length": 7
    }
  ]" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"
Spoiler only for a media object (image/video)
curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "media_type=IMAGE" \
  -d "image_url=<IMAGE_URL>" \
  -d "text=<TEXT>" \
  -d "is_spoiler_media=true" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"
Spoiler for both text and a media object (image/video)
curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "media_type=IMAGE" \
  -d "image_url=<IMAGE_URL>" \
  -d "text=<TEXT>" \
  -d "is_spoiler_media=true" \
  -d "text_entities=[
    {
      "entity_type": "SPOILER",
      "offset": 0,
      "length": 2
    },
    {
      "entity_type": "SPOILER",
      "offset": 2,
      "length": 7
    }
  ]" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Response

If the API call is successful, the Threads media container ID will be returned.

Step 2: Publish the media container

You can now publish using the returned Threads media container ID to create your single Threads post with spoilers.

Threads Carousel Posts

Step 1: Create a media container

Create a media container for each of the items to be included in the carousel.

Step 2: Create the carousel container

Spoilers for Threads carousel posts need to be provided during the carousel container creation phase.

  • If a spoiler needs to be added in the text field of the post, use the text_entities parameter.
  • If a spoiler needs to be added to the media object in the post, use the is_spoiler_media parameter.
  • If a spoiler needs to be added to the text and media objects in the post, use both the text_entities and is_spoiler_media parameters.

Note: If is_spoiler_media is set to true all attached media (i.e., images and videos) will be marked as spoilers.

Example requests

Spoiler only in the text field
curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "media_type=CAROUSEL" \
  -d "children=<MEDIA_ID_1>,<MEDIA_ID_2>,<MEDIA_ID_3>" \
  -d "text=<TEXT>" \
  -d "text_entities=[
    {
      "entity_type": "SPOILER",
      "text": "spoiler",
      "offset": 0,
      "length": 2
    },
    {
      "entity_type": "SPOILER",
      "text": "spoiler",
      "offset": 2,
      "length": 7
    }
  ]" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"
Spoiler only for a media object (image/video)
curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "media_type=CAROUSEL" \
  -d "children=<MEDIA_ID_1>,<MEDIA_ID_2>,<MEDIA_ID_3>" \
  -d "is_spoiler_media=true" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"
Spoiler for both text and a media object (image/video)
curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "media_type=CAROUSEL" \
  -d "children=<MEDIA_ID_1>,<MEDIA_ID_2>,<MEDIA_ID_3>" \
  -d "text=<TEXT>" \
  -d "is_spoiler_media=true" \
  -d "text_entities=[
    {
      "entity_type": "SPOILER",
      "text": "spoiler",
      "offset": 0,
      "length": 2
    },
    {
      "entity_type": "SPOILER",
      "text": "spoiler",
      "offset": 2,
      "length": 7
    }
  ]" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Response

If the API call is successful, the Threads media container ID will be returned.

Step 3: Publish the media container

You can now publish using the returned Threads media container ID to create your Threads carousel post with spoilers.

Learn More