Twitter/X Communities API

openapi: 3.0.0
info:
  description: X API v2 available endpoints
  version: '2.166'
  title: X API v2 Account Activity Communities 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: Communities
paths:
  /2/communities/search:
    get:
      security:
      - OAuth2UserToken:
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Communities
      summary: Search Communities
      description: Retrieves a list of Communities matching the specified search query.
      externalDocs:
        url: https://developer.x.com
      operationId: searchCommunities
      parameters:
      - name: query
        in: query
        description: Query to search communities.
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 4096
          example: Love
        style: form
      - name: max_results
        in: query
        description: The maximum number of search results to be returned by a request.
        required: false
        schema:
          type: integer
          minimum: 10
          maximum: 100
          format: int32
          default: 10
        style: form
      - name: next_token
        in: query
        description: This parameter is used to get the next 'page' of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
        required: false
        schema:
          $ref: '#/components/schemas/NextToken'
        style: form
      - name: pagination_token
        in: query
        description: This parameter is used to get the next 'page' of results. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified.
        required: false
        schema:
          $ref: '#/components/schemas/NextToken'
        style: form
      - $ref: '#/components/parameters/CommunityFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get2CommunitiesSearchResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/communities/{id}:
    get:
      security:
      - BearerToken: []
      - OAuth2UserToken:
        - list.read
        - tweet.read
        - users.read
      - UserToken: []
      tags:
      - Communities
      summary: Get Community by ID
      description: Retrieves details of a specific Community by its ID.
      externalDocs:
        url: https://developer.x.com/en/docs/x-api/communities/api-reference/get-communities-id
      operationId: getCommunitiesById
      parameters:
      - name: id
        in: path
        description: The ID of the Community.
        required: true
        schema:
          $ref: '#/components/schemas/CommunityId'
        style: simple
      - $ref: '#/components/parameters/CommunityFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get2CommunitiesIdResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    Get2CommunitiesIdResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Community'
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Problem'
    Community:
      type: object
      description: A X Community is a curated group of Posts.
      required:
      - id
      - name
      properties:
        created_at:
          type: string
          format: date-time
        id:
          $ref: '#/components/schemas/CommunityId'
        name:
          type: string
          description: The name of this Community.
    Get2CommunitiesSearchResponse:
      type: object
      properties:
        data:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Community'
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Problem'
        meta:
          type: object
          properties:
            next_token:
              $ref: '#/components/schemas/NextToken'
    Problem:
      type: object
      description: An HTTP Problem Details object, as defined in IETF RFC 7807 (https://tools.ietf.org/html/rfc7807).
      required:
      - type
      - title
      properties:
        detail:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
      discriminator:
        propertyName: type
        mapping:
          about:blank: '#/components/schemas/GenericProblem'
          https://api.twitter.com/2/problems/client-disconnected: '#/components/schemas/ClientDisconnectedProblem'
          https://api.twitter.com/2/problems/client-forbidden: '#/components/schemas/ClientForbiddenProblem'
          https://api.twitter.com/2/problems/conflict: '#/components/schemas/ConflictProblem'
          https://api.twitter.com/2/problems/disallowed-resource: '#/components/schemas/DisallowedResourceProblem'
          https://api.twitter.com/2/problems/duplicate-rules: '#/components/schemas/DuplicateRuleProblem'
          https://api.twitter.com/2/problems/invalid-request: '#/components/schemas/InvalidRequestProblem'
          https://api.twitter.com/2/problems/invalid-rules: '#/components/schemas/InvalidRuleProblem'
          https://api.twitter.com/2/problems/noncompliant-rules: '#/components/schemas/NonCompliantRulesProblem'
          https://api.twitter.com/2/problems/not-authorized-for-field: '#/components/schemas/FieldUnauthorizedProblem'
          https://api.twitter.com/2/problems/not-authorized-for-resource: '#/components/schemas/ResourceUnauthorizedProblem'
          https://api.twitter.com/2/problems/operational-disconnect: '#/components/schemas/OperationalDisconnectProblem'
          https://api.twitter.com/2/problems/resource-not-found: '#/components/schemas/ResourceNotFoundProblem'
          https://api.twitter.com/2/problems/resource-unavailable: '#/components/schemas/ResourceUnavailableProblem'
          https://api.twitter.com/2/problems/rule-cap: '#/components/schemas/RulesCapProblem'
          https://api.twitter.com/2/problems/streaming-connection: '#/components/schemas/ConnectionExceptionProblem'
          https://api.twitter.com/2/problems/unsupported-authentication: '#/components/schemas/UnsupportedAuthenticationProblem'
          https://api.twitter.com/2/problems/usage-capped: '#/components/schemas/UsageCapExceededProblem'
    NextToken:
      type: string
      description: The next token.
      minLength: 1
    CommunityId:
      type: string
      description: The unique identifier of this Community.
      pattern: ^[0-9]{1,19}$
      example: '1146654567674912769'
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
  parameters:
    CommunityFieldsParameter:
      name: community.fields
      in: query
      description: A comma separated list of Community fields to display.
      required: false
      schema:
        type: array
        description: The fields available for a Community object.
        minItems: 1
        uniqueItems: true
        items:
          type: string
          enum:
          - access
          - created_at
          - description
          - id
          - join_policy
          - member_count
          - name
        example:
        - access
        - created_at
        - description
        - id
        - join_policy
        - member_count
        - name
      explode: false
      style: form
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
    OAuth2UserToken:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.x.com/2/oauth2/authorize
          tokenUrl: https://api.x.com/2/oauth2/token
          scopes:
            block.read: View accounts you have blocked.
            bookmark.read: Read your bookmarked Posts.
            bookmark.write: Create and delete your bookmarks.
            dm.read: Read all your Direct Messages.
            dm.write: Send and manage your Direct Messages.
            follows.read: View accounts you follow and accounts following you.
            follows.write: Follow and unfollow accounts on your behalf.
            like.read: View Posts you have liked and likes you can see.
            like.write: Like and unlike Posts on your behalf.
            list.read: View Lists, members, and followers of Lists you created or are a member of, including private Lists.
            list.write: Create and manage Lists on your behalf.
            media.write: Upload media, such as photos and videos, on your behalf.
            mute.read: View accounts you have muted.
            mute.write: Mute and unmute accounts on your behalf.
            offline.access: Request a refresh token for the app.
            space.read: View all Spaces you have access to.
            timeline.read: View all Custom Timelines you can see, including public Custom Timelines from other developers.
            tweet.moderate.write: Hide and unhide replies to your Posts.
            tweet.read: View all Posts you can see, including those from protected accounts.
            tweet.write: Post and repost on your behalf.
            users.read: View any account you can see, including protected accounts.
    UserToken:
      type: http
      scheme: OAuth