Quickstart

This guide walks you through creating, updating, and deleting Lists. Reference for the Enterprise X API tier covering manage lists.

This guide walks you through creating, updating, and deleting Lists.

Prerequisites

Before you begin, you’ll need:

• A developer account with an approved App
• User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)

---

Create a List

1. Prepare your request

   Define the List name (required) and optional description and privacy settings:

   {
     "name": "Tech News",
     "description": "Top tech journalists and publications",
     "private": false
   }
   
2. Send the request

   cURL

   shellscript

   curl -X POST "https://api.x.com/2/lists" \
     -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Tech News",
       "description": "Top tech journalists and publications",
       "private": false
     }'
   

   from xdk import Client
   from xdk.oauth1_auth import OAuth1
   
   oauth1 = OAuth1(
       api_key="YOUR_API_KEY",
       api_secret="YOUR_API_SECRET",
       access_token="YOUR_ACCESS_TOKEN",
       access_token_secret="YOUR_ACCESS_TOKEN_SECRET"
   )
   
   client = Client(auth=oauth1)
   
   # Create a new List
   response = client.lists.create(
       name="Tech News",
       description="Top tech journalists and publications",
       private=False
   )
   
   print(f"List created: {response.data.id} - {response.data.name}")
   

   import { Client, OAuth1 } from "@xdevplatform/xdk";
   
   const oauth1 = new OAuth1({
     apiKey: "YOUR_API_KEY",
     apiSecret: "YOUR_API_SECRET",
     accessToken: "YOUR_ACCESS_TOKEN",
     accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET",
   });
   
   const client = new Client({ oauth1 });
   
   // Create a new List
   const response = await client.lists.create({
     name: "Tech News",
     description: "Top tech journalists and publications",
     private: false,
   });
   
   console.log(`List created: ${response.data?.id} - ${response.data?.name}`);
   
3. Review the response

   {
     "data": {
       "id": "1441162269824405510",
       "name": "Tech News"
     }
   }
   

   Save the id to update or delete the List later.

---

Update a List

Modify a List’s name, description, or privacy:

cURL

shellscript

curl -X PUT "https://api.x.com/2/lists/1441162269824405510" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech News & Insights",
    "description": "Updated description"
  }'

from xdk import Client
from xdk.oauth1_auth import OAuth1

oauth1 = OAuth1(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    access_token="YOUR_ACCESS_TOKEN",
    access_token_secret="YOUR_ACCESS_TOKEN_SECRET"
)

client = Client(auth=oauth1)

# Update a List
response = client.lists.update(
    "1441162269824405510",
    name="Tech News & Insights",
    description="Updated description"
)

print(f"Updated: {response.data.updated}")

import { Client, OAuth1 } from "@xdevplatform/xdk";

const oauth1 = new OAuth1({
  apiKey: "YOUR_API_KEY",
  apiSecret: "YOUR_API_SECRET",
  accessToken: "YOUR_ACCESS_TOKEN",
  accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET",
});

const client = new Client({ oauth1 });

// Update a List
const response = await client.lists.update("1441162269824405510", {
  name: "Tech News & Insights",
  description: "Updated description",
});

console.log(`Updated: ${response.data?.updated}`);

Response:

{
  "data": {
    "updated": true
  }
}

---

Delete a List

1. Get the List ID

   You need the ID of the List you want to delete.

2. Send the delete request

   cURL

   shellscript

   curl -X DELETE "https://api.x.com/2/lists/1441162269824405510" \
     -H "Authorization: Bearer $USER_ACCESS_TOKEN"
   

   from xdk import Client
   from xdk.oauth1_auth import OAuth1
   
   oauth1 = OAuth1(
       api_key="YOUR_API_KEY",
       api_secret="YOUR_API_SECRET",
       access_token="YOUR_ACCESS_TOKEN",
       access_token_secret="YOUR_ACCESS_TOKEN_SECRET"
   )
   
   client = Client(auth=oauth1)
   
   # Delete a List
   response = client.lists.delete("1441162269824405510")
   print(f"Deleted: {response.data.deleted}")
   

   import { Client, OAuth1 } from "@xdevplatform/xdk";
   
   const oauth1 = new OAuth1({
     apiKey: "YOUR_API_KEY",
     apiSecret: "YOUR_API_SECRET",
     accessToken: "YOUR_ACCESS_TOKEN",
     accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET",
   });
   
   const client = new Client({ oauth1 });
   
   // Delete a List
   const response = await client.lists.delete("1441162269824405510");
   console.log(`Deleted: ${response.data?.deleted}`);
   
3. Confirm deletion

   {
     "data": {
       "deleted": true
     }
   }
   

You can only delete Lists that you own.

---

Next steps

List members

Add and remove List members

List lookup

Retrieve List details

Integration guide

Key concepts and best practices

API Reference

Full endpoint documentation