Skip to main content
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

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
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
  }'
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
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"
  }'
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
curl -X DELETE "https://api.x.com/2/lists/1441162269824405510" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
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