Bookmarks

​

Introduction

​

Manage Bookmarks

We have two available methods for manage Bookmarks, POST and DELETE. The POST method lets you create Bookmarks. Likewise, the DELETE method allows you to delete a specific Bookmark. 

There is a per-user rate limit of 50 requests per 15 minutes for the POST and DELETE methods.

Since you are making requests on behalf of a user with the manage Bookmarks endpoints, you must authenticate by generating a user Access Token with OAuth 2.0. You can use the Authorization Code with PKCE grant flow to do so. To use this endpoint you must pass in the scopes tweet.read, users.read, and  bookmark.write.

​

Bookmarks lookup

The Bookmarks lookup endpoint has one method available, GET. This method allows you to get Bookmarks back from yourself or an authenticated account. Pagination tokens will be provided for paging through large sets of results for this endpoint.

There is a per-user rate limit of 180 requests per 15 min window for the GET method. With this endpoint you will get back 800 of your most recent Bookmarked Posts.

Since you are making requests on behalf of a user with the lookup Bookmarks endpoints, you must authenticate by generating a user Access Token with OAuth 2.0. You can use the Authorization Code with PKCE grant flow to do so. To use this endpoint you must pass in the scopes tweet.read, users.read, and bookmark.read.

Account setup

To access these endpoints, you will need:

• An approved developer account.
• To authenticate using the keys and tokens from a developer App that is located within a Project. 

Learn more about getting access to the X API v2 endpoints in our getting started guide.

​

Getting started with the manage Bookmarks endpoints

This quick start guide will help you make your first request to the manage Bookmarks endpoints using Postman.

If you would like to see sample code in different languages, please visit our X API v2 sample code GitHub repository. 

​

Steps to build a manage Bookmarks request

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we are going to use the Postman tool here to simplify the process.

To load the X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the “Bookmarks” folder, and select “Create a Bookmark”.

Step two: Authenticate your request

To make a successful request to this endpoint, you will need to use OAuth 2.0 Authorization Code Flow with PKCE. You can generate an access token within Postman. 

If you go to the tab entitled “Authorization” and select “OAuth 2.0”.

In this tab, be sure to follow these steps:

1. Name your token

2. Select the Grant Type as Authorization Code (with PKCE)

3. Update the parameters:

   Callback URL - https://www.example.com

   This should be matching the callback URL you set in your auth settings page in the Developer Portal.

   Auth URL - https://twitter.com/i/oauth2/authorize

   Access Token URL - https://api.x.com/2/oauth2/token

   Client ID - Cut and paste OAuth 2.0 client ID from the Developer Portal

   **Client Secret **- Cut and paste OAuth 2.0 client ID from the Developer Portal. You will need this only if you are using an App type that is a confidential client.

4. Update the scopes with the following values: post.read users.read bookmark.write

5. Populate the field state with “State”

6. Click where it says “Generate Token”

7. Press the save icon to save the folder changes.

You may get a message that you are not logged into X. If you get this error, you will need to log in to the X account inside of Postman you are trying to post on behalf of.

Step three: Specify a user

With this endpoint, you must specify the user ID whose followers you would like to receive in the response. For example, the user ID for @XDevelopers is 2244994945.

In Postman, navigate to the “Params” tab and enter the ID of yourself or an authenticated user as the value for the id parameter.

Step four: Specify Specify a Post you want to Bookmark

You will want to navigate to the “Body” tab and make sure the Post ID is set to the one you are looking to save to your Bookmarks. The JSON payload should look similar to the one below.

{"tweet_id": "1460323737035677698"}

Step five: Make your request and review your response

Once you have everything set up, hit the “Send” button, and you will receive a similar response to the following example response:

{
   "data": {
       "bookmarked": true
   }
}

To delete a Post, select the “Remove a Bookmark” request also found in the “Bookmarks” folder of the X API v2 collection loaded in Postman. You will first want to specify the user ID of the user you are making a request on behalf of as the value for the “id” column. This endpoint also requires the ID of the Post you wish to delete. Then, in the “Params” tab, enter the ID of the Post you wish to delete as the value for the “tweet_id” column. 

When you have a successful delete request, you will receive a response similar to the following example: 

{
   "data": {
       "bookmarked": false
   }
}

​

Quick start

​

Getting started with the Bookmarks lookup endpoint

This quick start guide will help you make your first request to the Bookmarks lookup endpoint using Postman.

Please visit our X API v2 sample code GitHub repository if you want to see sample code in different languages.

​

Prerequisites

To complete this guide, you will need to have a set of keys and tokens to authenticate your request. You can generate these keys and tokens by following these steps:

• Sign up for a developer account and receive approval.
• Create a Project and an associated developer App in the developer portal.
• Navigate to your App’s “Keys and tokens” page to generate the required credentials. Make sure to save all credentials in a secure location.

​

Steps to build a Bookmarks lookup request

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we will use the Postman tool here to simplify the process.

To load the X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the “Bookmarks” folder, and select “ Bookmarks lookup”.

Step two: Authenticate your request

To make a successful request to this endpoint, you will need to use OAuth 2.0 Authorization Code Flow with PKCE. You can generate an access token within Postman. 

If you go to the tab entitled “Authorization” and select “OAuth 2.0”.

In this tab, be sure to follow these steps:

1. Name your token

2. Select the Grant Type as Authorization Code (with PKCE)

3. Update the parameters:

   Callback URL - https://www.example.com

   This should be matching the callback URL you set in your auth settings page in the Developer Portal.

   Auth URL - https://twitter.com/i/oauth2/authorize

   Access Token URL - https://api.x.com/2/oauth2/token

   Client ID - Cut and paste OAuth 2.0 client ID from the Developer Portal

   Client Secret - Cut and paste OAuth 2.0 client ID from the Developer Portal. You will need this only if you are using an App type that is a confidential client.

4. Update the scopes with the following values: post.read users.read bookmark.read

5. Populate the field state with “State”

6. Click where it says “Generate Token”

7. Press the save icon to save the folder changes.

You may get a message that you are not logged into X. If you get this error, you will need to log in to the X account inside of Postman you are trying to post on behalf of.

Step three: Specify a user

With this endpoint, you must specify the user ID whose followers you would like to receive in the response. For example, the user ID for @XDevelopers is2244994945. In Postman, navigate to the “Params” tab and enter the ID of yourself or an authenticated user as the value for the id parameter.

Step four: Make your request and review your response

Once you have everything set up, hit the “Send” button and you will receive a similar response to the following example response:

{
   "data": [
       {
           "id": "1501258597237342208",
           "text": "🗣 Have you built a project using the Twitter API you’d like to share with the community? We’d love to hear from you. Share your project with us!"
       },
       {
           "id": "1501258542258348032",
           "text": "🧰🛠 This is just one way developer innovation helps make Twitter a better place. You can find other ready-to-use tools built by our developer community in our Twitter Toolbox here ⬇️ https://t.co/rK0X30JSYU"
       },
       {
           "id": "1501257716941000709",
           "text": "📣Today’s an important day! \nWe’ve partnered with @Jigsaw on the launch of this new tool. This collaboration allows NGOs and nonprofits to build tools that help people stay safe on Twitter by addressing the needs and preferences of the communities they serve. Learn More ⬇️ https://t.co/MmznmgxoWT"
       },
       {
           "id": "1501686770810900485",
           "text": "Join us tomorrow for a continued conversation on customizing timelines and how this might work for developers. And stay tuned for more Spaces coming up next week. 👀 https://t.co/P4JTc14mdC"
       },
       {
           "id": "1501596763194593285",
           "text": "Developer innovation is always important, including in times of crisis. If you're building tools to help connect people, keep them safe, or share information with the world, we're here to support—reply to this Tweet to tell us more about your app."
       }
   ]
}

​

Getting started with the manage Bookmarks endpoints

This quick start guide will help you make your first request to the manage Bookmarks endpoints using Postman.

If you would like to see sample code in different languages, please visit our X API v2 sample code GitHub repository. 

​

Prerequisites

To complete this guide, you will need to have a set of keys and tokens to authenticate your request. You can generate these keys and tokens by following these steps:

• Sign up for a developer account and receive approval.
• Create a Project and an associated developer App in the developer portal.
• Navigate to your App’s “Keys and tokens” page to generate the required credentials. Make sure to save all credentials in a secure location.

​

Steps to build a manage Bookmarks request

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we are going to use the Postman tool here to simplify the process.

To load the X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the “Bookmarks” folder, and select “Create a Bookmark”.

Step two: Authenticate your request

To make a successful request to this endpoint, you will need to use OAuth 2.0 Authorization Code Flow with PKCE. You can generate an access token within Postman. 

If you go to the tab entitled “Authorization” and select “OAuth 2.0”.

In this tab, be sure to follow these steps:

1. Name your token

2. Select the Grant Type as Authorization Code (with PKCE)

3. Update the parameters:

   Callback URL - https://www.example.com

   This should be matching the callback URL you set in your auth settings page in the Developer Portal.

   Auth URL - https://twitter.com/i/oauth2/authorize

   Access Token URL - https://api.x.com/2/oauth2/token

   Client ID - Cut and paste OAuth 2.0 client ID from the Developer Portal

   **Client Secret **- Cut and paste OAuth 2.0 client ID from the Developer Portal. You will need this only if you are using an App type that is a confidential client.

4. Update the scopes with the following values: post.read users.read bookmark.write

5. Populate the field state with “State”

6. Click where it says “Generate Token”

7. Press the save icon to save the folder changes.

You may get a message that you are not logged into X. If you get this error, you will need to log in to the X account inside of Postman you are trying to post on behalf of.

Step three: Specify a user

With this endpoint, you must specify the user ID whose followers you would like to receive in the response. For example, the user ID for @XDevelopers is 2244994945.

In Postman, navigate to the “Params” tab and enter the ID of yourself or an authenticated user as the value for the id parameter.

Step four: Specify Specify a Post you want to Bookmark

You will want to navigate to the “Body” tab and make sure the Post ID is set to the one you are looking to save to your Bookmarks. The JSON payload should look similar to the one below.

{"tweet_id": "1460323737035677698"}

Step five: Make your request and review your response

Once you have everything set up, hit the “Send” button, and you will receive a similar response to the following example response:

{
   "data": {
       "bookmarked": true
   }
}

To delete a Post, select the “Remove a Bookmark” request also found in the “Bookmarks” folder of the X API v2 collection loaded in Postman. You will first want to specify the user ID of the user you are making a request on behalf of as the value for the “id” column. This endpoint also requires the ID of the Post you wish to delete. Then, in the “Params” tab, enter the ID of the Post you wish to delete as the value for the “tweet_id” column. 

When you have a successful delete request, you will receive a response similar to the following example: 

{
   "data": {
       "bookmarked": false
   }
}

​

Integration guide

This page contains information on several tools and critical concepts that you should know as you integrate the manage Bookmarks endpoints into your system. We’ve broken the page into a couple of different sections:

• Helpful tools
• Key Concepts
  • Authentication
  • Developer portal, Projects, and Apps
  • Rate limits

​

Helpful tools

Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with:

​

Postman

Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our “Using Postman” page. 

​

Code samples

Are you interested in getting set up with this endpoint with some code in your preferred coding language? We’ve got a handful of different code samples available that you can use as a starting point on our Github page.

​

Third-party libraries

Take advantage of one of our communities’ third-party libraries to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag.

​

Key concepts

​

Authentication

All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. 

These specific endpoints require the use of OAuth 2.0 Authorization Code Flow with PKCE, which means that you must use a set of keys and user Access Tokens to make a successful request. The Access Tokens must be associated with the user that you are requesting on behalf of. If you want to generate a set of Access Tokens for another user, they must authorize or authenticate your App using an Authorize URL.

Please note that OAuth 2.0 can be tricky to use. If you are not familiar with this authentication method, we recommend using a library or a tool like Postman to properly authenticate your requests.

​

Developer portal, Projects, and developer Apps

To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must have a developer account, set up a Project within that account, and created a developer App within that Project. You can then find your keys and tokens within your developer App. 

​

Rate limits

Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, rate limits are placed on each endpoint that limits the number of requests that you can make on behalf of your app or on behalf of an authenticated user. 

These endpoints are rate limited at the user level, meaning that the authenticated user that you are making the request on behalf of can only call the endpoint a certain number of times across any developer App. There is a user rate limit of 180 requests per 15 min window for the GET method. With the GET method of the Bookmarks lookup endpoint you will get back 800 of your most recent Bookmarked Posts. Additionally, there is a user rate limit of 50 requests per 15 minutes for the POST and DELETE methods. 

​

API Reference index

For the complete API reference, select an endpoint from the list:

​

Bookmarks lookup

​

Manage Bookmarks

​

DELETE /2/users/:id/bookmarks/:tweet_id

Allows a user or authenticated user ID to remove a Bookmark of a Tweet.

​

Endpoint URL

https://api.x.com/2/users/:id/bookmarks/:tweet_id

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

Example code with offical SDKs

• TypeScript
• Java

(async () => {
  try {
    const removeBookmark =
      await twitterClient.bookmarks.usersIdBookmarksDelete(
        //The ID of the user whose bookmark is to be removed.
        "2244994945",

        //The ID of the tweet that the user is removing from bookmarks
        "1228393702244134912"
      );
    console.dir(removeBookmark, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Successful response

{
  "data": {
    "bookmarked": false
  }
}

​

Response fields

​

POST /2/users/:id/bookmarks

Causes the user ID of an authenticated user identified in the path parameter to Bookmark the target Tweet provided in the request body.

​

Endpoint URL

https://api.x.com/2/users/:id/bookmarks

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

JSON body parameters

​

Example code with offical SDKs

• Java

• TypeScript
• Java

(async () => {
  try {
    const postBookmark = await twitterClient.bookmarks.postUsersIdBookmarks(
      //User ID
      "2244994945",
      {
        tweet_id: "1228393702244134912",
      }
    );
    console.dir(postBookmark, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Successful response

{
  "data": {
    "bookmarked": true
  }
}

​

Response fields

​

GET /2/users/:id/bookmarks

Allows you to get an authenticated user’s 800 most recent bookmarked Tweets.

​

Endpoint URL

https://api.x.com/2/users/:id/bookmarks

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

Query parameters

​

Example code with offical SDKs

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

(async () => {
  try {
    const getUserBookmarks =
      await twitterClient.bookmarks.getUsersIdBookmarks(
        //User ID
        "2244994945"
      );
    console.dir(getUserBookmarks, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default fields
• Optional fields

{
  "data": [
    {
      "id": "1362449997430542337",
      "text": "Honored to be the first developer to be featured in @TwitterDev's love fest 🥰♥️😍 https://t.co/g8TsPoZsij"
    },
    {
      "id": "1365416026435854338",
      "text": "We're so happy for our Official Partner @Brandwatch and their big news. https://t.co/3DwWBNSq0o https://t.co/bDUGbgPkKO"
    },
    {
      "id": "1296487407475462144",
      "text": "Check out this feature on @TwitterDev to learn more about how we're mining social media data to make sense of this evolving #publichealth crisis https://t.co/sIFLXRSvEX."
    },
    {
      "id": "1294346980072624128",
      "text": "I awake from five years of slumber https://t.co/OEPVyAFcfB"
    },
    {
      "id": "1283153843367206912",
      "text": "@wongmjane Wish we could tell you more, but I’m only a teapot 👀"
    }
  ],
  "meta": {
    "result_count": 5,
    "next_token": "zldjwdz3w6sba13nbs0mbravfipbtqvbiqplg9h0p4k"
  }
}

​

Response fields