Quickstart

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

PrerequisitesBefore 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

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
}

Send the request

cURL

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}`);

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

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

Get the List ID

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

Send the delete request

cURL

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}`);

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

​Create a List

​Update a List

​Delete a List

​Next steps

List members

List lookup

Integration guide

API Reference

Create a List

Update a List

Delete a List

Next steps