X (Twitter)

X (Twitter) Lists API

Endpoints related to retrieving, managing Lists

GitHub OpenAPI

Operations 17

POST /2/lists X Create List #
DELETE /2/lists/{id} X Delete List #
GET /2/lists/{id} X Get List by ID #
PUT /2/lists/{id} X Update List #
GET /2/lists/{id}/followers X Get List Followers #
GET /2/lists/{id}/members X Get List Members #
POST /2/lists/{id}/members X Add List Member #
DELETE /2/lists/{id}/members/{user_id} X Remove List Member #
GET /2/lists/{id}/tweets X Get List Posts #
GET /2/users/{id}/followed_lists X Get Followed Lists #
POST /2/users/{id}/followed_lists X Follow List #
DELETE /2/users/{id}/followed_lists/{list_id} X Unfollow List #
GET /2/users/{id}/list_memberships X Get List Memberships #
GET /2/users/{id}/owned_lists X Get Owned Lists #
GET /2/users/{id}/pinned_lists X Get Pinned Lists #
POST /2/users/{id}/pinned_lists X Pin List #
DELETE /2/users/{id}/pinned_lists/{list_id} X Unpin List #

Documentation

📖
Documentation
https://docs.x.com/x-api
📖
GettingStarted
https://docs.x.com/x-api/getting-started/make-your-first-request
📖
APIReference
https://docs.x.com/x-api
📖
Authentication
https://docs.x.com/resources/fundamentals/authentication
📖
RateLimits
https://docs.x.com/x-api/fundamentals/rate-limits

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/twitter/refs/heads/main/openapi/twitter-lists-api-openapi.yml

Other Resources

🔗
SDKs
https://docs.x.com/sdks-and-tools/python-xdk
🔗
SDKs
https://docs.x.com/sdks-and-tools/typescript-xdk
🔗
GraphQL
https://raw.githubusercontent.com/api-evangelist/twitter/refs/heads/main/graphql/twitter-graphql.md

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/twitter-lists-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

twitter-lists-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  description: X API v2 available endpoints
  version: '2.161'
  title: X API v2 Account Activity Lists API
  termsOfService: https://developer.x.com/en/developer-terms/agreement-and-policy.html
  contact:
    name: X Developers
    url: https://developer.x.com/
  license:
    name: X Developer Agreement and Policy
    url: https://developer.x.com/en/developer-terms/agreement-and-policy.html
servers:
- description: X API
  url: https://api.x.com
tags:
- name: Lists
  description: Endpoints related to retrieving, managing Lists
  externalDocs:
    description: Find out more
    url: https://developer.twitter.com/en/docs/twitter-api/lists
paths:
  /2/lists:
    post:
      security:
      - OAuth2UserToken:
        - list.read
        - list.write
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Create List
      description: Creates a new List for the authenticated user.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/post-lists
      operationId: createLists
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListCreateRequest'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCreateResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2/lists/{id}:
    delete:
      security:
      - OAuth2UserToken:
        - list.write
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Delete List
      description: Deletes a specific List owned by the authenticated user by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/delete-lists-id
      operationId: deleteLists
      parameters:
      - name: id
        in: path
        description: The ID of the List to delete.
        required: true
        schema:
          $ref: '#/components/schemas/ListId'
        style: simple
        example: '1234567890'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDeleteResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      security:
      - BearerToken: []
      - OAuth2UserToken:
        - list.read
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Get List by ID
      description: Retrieves details of a specific List by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/list-lookup/api-reference/get-lists-id
      operationId: getListsById
      parameters:
      - name: id
        in: path
        description: The ID of the List.
        required: true
        schema:
          $ref: '#/components/schemas/ListId'
        style: simple
        example: '1234567890'
      - $ref: '#/components/parameters/ListFieldsParameter'
      - $ref: '#/components/parameters/ListExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get2ListsIdResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      security:
      - OAuth2UserToken:
        - list.write
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Update List
      description: Updates the details of a specific List owned by the authenticated user by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/put-lists-id
      operationId: updateLists
      parameters:
      - name: id
        in: path
        description: The ID of the List to modify.
        required: true
        schema:
          $ref: '#/components/schemas/ListId'
        style: simple
        example: '1234567890'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListUpdateRequest'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUpdateResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2/lists/{id}/followers:
    get:
      security:
      - BearerToken: []
      - OAuth2UserToken:
        - list.read
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Get List Followers
      description: Retrieves a list of Users who follow a specific List by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/get-users-id-followers
      operationId: getListsFollowers
      parameters:
      - name: id
        in: path
        description: The ID of the List.
        required: true
        schema:
          $ref: '#/components/schemas/ListId'
        style: simple
        example: '1234567890'
      - name: max_results
        in: query
        description: The maximum number of results.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 100
        style: form
        example: 10
      - name: pagination_token
        in: query
        description: This parameter is used to get a specified 'page' of results.
        required: false
        schema:
          $ref: '#/components/schemas/PaginationTokenLong'
        style: form
        example: next_token_abc123
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/UserExpansionsParameter'
      - $ref: '#/components/parameters/TweetFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get2ListsIdFollowersResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2/lists/{id}/members:
    get:
      security:
      - BearerToken: []
      - OAuth2UserToken:
        - list.read
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Get List Members
      description: Retrieves a list of Users who are members of a specific List by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/get-users-id-list_memberships
      operationId: getListsMembers
      parameters:
      - name: id
        in: path
        description: The ID of the List.
        required: true
        schema:
          $ref: '#/components/schemas/ListId'
        style: simple
        example: '1234567890'
      - name: max_results
        in: query
        description: The maximum number of results.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 100
        style: form
        example: 10
      - name: pagination_token
        in: query
        description: This parameter is used to get a specified 'page' of results.
        required: false
        schema:
          $ref: '#/components/schemas/PaginationTokenLong'
        style: form
        example: next_token_abc123
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/UserExpansionsParameter'
      - $ref: '#/components/parameters/TweetFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get2ListsIdMembersResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      security:
      - OAuth2UserToken:
        - list.write
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Add List Member
      description: Adds a User to a specific List by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/post-lists-id-members
      operationId: addListsMember
      parameters:
      - name: id
        in: path
        description: The ID of the List for which to add a member.
        required: true
        schema:
          $ref: '#/components/schemas/ListId'
        style: simple
        example: '1234567890'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListAddUserRequest'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMutateResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2/lists/{id}/members/{user_id}:
    delete:
      security:
      - OAuth2UserToken:
        - list.write
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Remove List Member
      description: Removes a User from a specific List by its ID and the User’s ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/delete-lists-id-members-user_id
      operationId: removeListsMemberByUserId
      parameters:
      - name: id
        in: path
        description: The ID of the List to remove a member.
        required: true
        schema:
          $ref: '#/components/schemas/ListId'
        style: simple
        example: '1234567890'
      - name: user_id
        in: path
        description: The ID of User that will be removed from the List.
        required: true
        schema:
          $ref: '#/components/schemas/UserId'
        style: simple
        example: '1234567890'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMutateResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2/lists/{id}/tweets:
    get:
      security:
      - BearerToken: []
      - OAuth2UserToken:
        - list.read
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Get List Posts
      description: Retrieves a list of Posts associated with a specific List by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/list-tweets/api-reference/get-lists-id-tweets
      operationId: getListsPosts
      parameters:
      - name: id
        in: path
        description: The ID of the List.
        required: true
        schema:
          $ref: '#/components/schemas/ListId'
        style: simple
        example: '1234567890'
      - name: max_results
        in: query
        description: The maximum number of results.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 100
        style: form
        example: 10
      - name: pagination_token
        in: query
        description: This parameter is used to get the next 'page' of results.
        required: false
        schema:
          $ref: '#/components/schemas/PaginationToken36'
        style: form
        example: next_token_abc123
      - $ref: '#/components/parameters/TweetFieldsParameter'
      - $ref: '#/components/parameters/TweetExpansionsParameter'
      - $ref: '#/components/parameters/MediaFieldsParameter'
      - $ref: '#/components/parameters/PollFieldsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/PlaceFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get2ListsIdTweetsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2/users/{id}/followed_lists:
    get:
      security:
      - BearerToken: []
      - OAuth2UserToken:
        - list.read
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Get Followed Lists
      description: Retrieves a list of Lists followed by a specific User by their ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/get-users-id-followed_lists
      operationId: getUsersFollowedLists
      parameters:
      - name: id
        in: path
        description: The ID of the User to lookup.
        required: true
        example: '2244994945'
        schema:
          $ref: '#/components/schemas/UserId'
        style: simple
      - name: max_results
        in: query
        description: The maximum number of results.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 100
        style: form
        example: 10
      - name: pagination_token
        in: query
        description: This parameter is used to get a specified 'page' of results.
        required: false
        schema:
          $ref: '#/components/schemas/PaginationTokenLong'
        style: form
        example: next_token_abc123
      - $ref: '#/components/parameters/ListFieldsParameter'
      - $ref: '#/components/parameters/ListExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get2UsersIdFollowedListsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      security:
      - OAuth2UserToken:
        - list.write
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Follow List
      description: Causes the authenticated user to follow a specific List by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/post-users-id-followed-lists
      operationId: followList
      parameters:
      - name: id
        in: path
        description: The ID of the authenticated source User that will follow the List.
        required: true
        schema:
          $ref: '#/components/schemas/UserIdMatchesAuthenticatedUser'
        style: simple
        example: '1234567890'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListFollowedRequest'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFollowedResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2/users/{id}/followed_lists/{list_id}:
    delete:
      security:
      - OAuth2UserToken:
        - list.write
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Unfollow List
      description: Causes the authenticated user to unfollow a specific List by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/delete-users-id-followed-lists-list_id
      operationId: unfollowList
      parameters:
      - name: id
        in: path
        description: The ID of the authenticated source User that will unfollow the List.
        required: true
        schema:
          $ref: '#/components/schemas/UserIdMatchesAuthenticatedUser'
        style: simple
        example: '1234567890'
      - name: list_id
        in: path
        description: The ID of the List to unfollow.
        required: true
        schema:
          $ref: '#/components/schemas/ListId'
        style: simple
        example: '1234567890'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFollowedResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2/users/{id}/list_memberships:
    get:
      security:
      - BearerToken: []
      - OAuth2UserToken:
        - list.read
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Get List Memberships
      description: Retrieves a list of Lists that a specific User is a member of by their ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/get-users-id-list_memberships
      operationId: getUsersListMemberships
      parameters:
      - name: id
        in: path
        description: The ID of the User to lookup.
        required: true
        example: '2244994945'
        schema:
          $ref: '#/components/schemas/UserId'
        style: simple
      - name: max_results
        in: query
        description: The maximum number of results.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 100
        style: form
        example: 10
      - name: pagination_token
        in: query
        description: This parameter is used to get a specified 'page' of results.
        required: false
        schema:
          $ref: '#/components/schemas/PaginationTokenLong'
        style: form
        example: next_token_abc123
      - $ref: '#/components/parameters/ListFieldsParameter'
      - $ref: '#/components/parameters/ListExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get2UsersIdListMembershipsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2/users/{id}/owned_lists:
    get:
      security:
      - BearerToken: []
      - OAuth2UserToken:
        - list.read
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Get Owned Lists
      description: Retrieves a list of Lists owned by a specific User by their ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/list-lookup/api-reference/get-users-id-owned_lists
      operationId: getUsersOwnedLists
      parameters:
      - name: id
        in: path
        description: The ID of the User to lookup.
        required: true
        example: '2244994945'
        schema:
          $ref: '#/components/schemas/UserId'
        style: simple
      - name: max_results
        in: query
        description: The maximum number of results.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 100
        style: form
        example: 10
      - name: pagination_token
        in: query
        description: This parameter is used to get a specified 'page' of results.
        required: false
        schema:
          $ref: '#/components/schemas/PaginationTokenLong'
        style: form
        example: next_token_abc123
      - $ref: '#/components/parameters/ListFieldsParameter'
      - $ref: '#/components/parameters/ListExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get2UsersIdOwnedListsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2/users/{id}/pinned_lists:
    get:
      security:
      - OAuth2UserToken:
        - list.read
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Get Pinned Lists
      description: Retrieves a list of Lists pinned by the authenticated user.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/pinned-lists/api-reference/get-users-id-pinned_lists
      operationId: getUsersPinnedLists
      parameters:
      - name: id
        in: path
        description: The ID of the authenticated source User for whom to return results.
        required: true
        schema:
          $ref: '#/components/schemas/UserIdMatchesAuthenticatedUser'
        style: simple
        example: '1234567890'
      - $ref: '#/components/parameters/ListFieldsParameter'
      - $ref: '#/components/parameters/ListExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get2UsersIdPinnedListsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      security:
      - OAuth2UserToken:
        - list.write
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Pin List
      description: Causes the authenticated user to pin a specific List by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/pinned-lists/api-reference/post-users-id-pinned-lists
      operationId: pinList
      parameters:
      - name: id
        in: path
        description: The ID of the authenticated source User that will pin the List.
        required: true
        schema:
          $ref: '#/components/schemas/UserIdMatchesAuthenticatedUser'
        style: simple
        example: '1234567890'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListPinnedRequest'
        required: true
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPinnedResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2/users/{id}/pinned_lists/{list_id}:
    delete:
      security:
      - OAuth2UserToken:
        - list.write
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Lists
      summary: X Unpin List
      description: Causes the authenticated user to unpin a specific List by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/lists/pinned-lists/api-reference/delete-users-id-pinned-lists-list_id
      operationId: unpinList
      parameters:
      - name: id
        in: path
        description: The ID of the authenticated source User for whom to return results.
        required: true
        schema:
          $ref: '#/components/schemas/UserIdMatchesAuthenticatedUser'
        style: simple
        example: '1234567890'
      - name: list_id
        in: path
        description: The ID of the List to unpin.
        required: true
        schema:
          $ref: '#/components/schemas/ListId'
        style: simple
        example: '1234567890'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUnpinResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    NextToken:
      type: string
      description: The next token.
      minLength: 1
    CashtagFields:
      type: object
      description: Represent the portion of text recognized as a Cashtag, and its start and end position within the text.
      required:
      - tag
      properties:
        tag:
          type: string
          example: TWTR
    Get2ListsIdResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/List'
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Problem'
        includes:
          $ref: '#/components/schemas/Expansions'
    NoteTweetText:
      type: string
      description: The note content of the Tweet.
      example: Learn how to use the user Tweet timeline and user mention timeline endpoints in the X API v2 to explore Tweet\u2026 https:\/\/t.co\/56a0vZUx7i
    PlaceId:
      type: string
      description: The identifier for this place.
      example: f7eb2fa2fea288b1
    Poll:
      type: object
      description: Represent a Poll attached to a Tweet.
      required:
      - id
      - options
      properties:
        duration_minutes:
          type: integer
          minimum: 5
          maximum: 10080
          format: int32
        end_datetime:
          type: string
          format: date-time
        id:
          $ref: '#/components/schemas/PollId'
        options:
          type: array
          minItems: 2
          maxItems: 4
          items:
            $ref: '#/components/schemas/PollOption'
        voting_status:
          type: string
          enum:
          - open
          - closed
    ListDeleteResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            deleted:
              type: boolean
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Problem'
    ListUpdateResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            updated:
              type: boolean
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Problem'
    Media:
      type: object
      required:
      - type
      properties:
        height:
          $ref: '#/components/schemas/MediaHeight'
        media_key:
          $ref: '#/components/schemas/MediaKey'
        type:
          type: string
        width:
          $ref: '#/components/schemas/MediaWidth'
      discriminator:
        propertyName: type
        mapping:
          animated_gif: '#/components/schemas/AnimatedGif'
          photo: '#/components/schemas/Photo'
          video: '#/components/schemas/Video'
    ListMutateResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            is_member:
              type: boolean
        errors:
          type: array
          minItems: 1
        

# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twitter/refs/heads/main/openapi/twitter-lists-api-openapi.yml