X API v2 — Spaces

naftiko: 1.0.0-alpha2
info:
  label: X API v2 — Spaces
  description: 'X API v2 — Spaces. 6 operations. Lead operation: X Get Spaces by IDs. Self-contained Naftiko capability covering
    one Twitter business surface.'
  tags:
  - Twitter
  - Spaces
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    TWITTER_API_KEY: TWITTER_API_KEY
capability:
  consumes:
  - type: http
    namespace: x-spaces
    baseUri: https://api.x.com
    description: X API v2 — Spaces business capability. Self-contained, no shared references.
    resources:
    - name: 2-spaces
      path: /2/spaces
      operations:
      - name: getspacesbyids
        method: GET
        description: X Get Spaces by IDs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ids
          in: query
          type: array
          description: The list of Space IDs to return.
          required: true
    - name: 2-spaces-by-creator_ids
      path: /2/spaces/by/creator_ids
      operations:
      - name: getspacesbycreatorids
        method: GET
        description: X Get Spaces by Creator IDs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: user_ids
          in: query
          type: array
          description: The IDs of Users to search through.
          required: true
    - name: 2-spaces-search
      path: /2/spaces/search
      operations:
      - name: searchspaces
        method: GET
        description: X Search Spaces
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: The search query.
          required: true
        - name: state
          in: query
          type: string
          description: The state of Spaces to search for.
        - name: max_results
          in: query
          type: integer
          description: The number of results to return.
    - name: 2-spaces-id
      path: /2/spaces/{id}
      operations:
      - name: getspacesbyid
        method: GET
        description: X Get Space by ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the Space to be retrieved.
          required: true
    - name: 2-spaces-id-buyers
      path: /2/spaces/{id}/buyers
      operations:
      - name: getspacesbuyers
        method: GET
        description: X Get Space Ticket Buyers
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the Space to be retrieved.
          required: true
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get a specified 'page' of results.
        - name: max_results
          in: query
          type: integer
          description: The maximum number of results.
    - name: 2-spaces-id-tweets
      path: /2/spaces/{id}/tweets
      operations:
      - name: getspacesposts
        method: GET
        description: X Get Space Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the Space to be retrieved.
          required: true
        - name: max_results
          in: query
          type: integer
          description: The number of Posts to fetch from the provided space. If not provided, the value will default to the
            maximum of 100.
    authentication:
      type: bearer
      token: '{{env.TWITTER_API_KEY}}'
  exposes:
  - type: rest
    namespace: x-spaces-rest
    port: 8080
    description: REST adapter for X API v2 — Spaces. One Spectral-compliant resource per consumed operation, prefixed with
      /v1.
    resources:
    - path: /v1/2/spaces
      name: 2-spaces
      description: REST surface for 2-spaces.
      operations:
      - method: GET
        name: getspacesbyids
        description: X Get Spaces by IDs
        call: x-spaces.getspacesbyids
        with:
          ids: rest.ids
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/spaces/by/creator-ids
      name: 2-spaces-by-creator-ids
      description: REST surface for 2-spaces-by-creator_ids.
      operations:
      - method: GET
        name: getspacesbycreatorids
        description: X Get Spaces by Creator IDs
        call: x-spaces.getspacesbycreatorids
        with:
          user_ids: rest.user_ids
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/spaces/search
      name: 2-spaces-search
      description: REST surface for 2-spaces-search.
      operations:
      - method: GET
        name: searchspaces
        description: X Search Spaces
        call: x-spaces.searchspaces
        with:
          query: rest.query
          state: rest.state
          max_results: rest.max_results
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/spaces/{id}
      name: 2-spaces-id
      description: REST surface for 2-spaces-id.
      operations:
      - method: GET
        name: getspacesbyid
        description: X Get Space by ID
        call: x-spaces.getspacesbyid
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/spaces/{id}/buyers
      name: 2-spaces-id-buyers
      description: REST surface for 2-spaces-id-buyers.
      operations:
      - method: GET
        name: getspacesbuyers
        description: X Get Space Ticket Buyers
        call: x-spaces.getspacesbuyers
        with:
          id: rest.id
          pagination_token: rest.pagination_token
          max_results: rest.max_results
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/spaces/{id}/tweets
      name: 2-spaces-id-tweets
      description: REST surface for 2-spaces-id-tweets.
      operations:
      - method: GET
        name: getspacesposts
        description: X Get Space Posts
        call: x-spaces.getspacesposts
        with:
          id: rest.id
          max_results: rest.max_results
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: x-spaces-mcp
    port: 9090
    transport: http
    description: MCP adapter for X API v2 — Spaces. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: x-get-spaces-ids
      description: X Get Spaces by IDs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: x-spaces.getspacesbyids
      with:
        ids: tools.ids
      outputParameters:
      - type: object
        mapping: $.
    - name: x-get-spaces-creator-ids
      description: X Get Spaces by Creator IDs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: x-spaces.getspacesbycreatorids
      with:
        user_ids: tools.user_ids
      outputParameters:
      - type: object
        mapping: $.
    - name: x-search-spaces
      description: X Search Spaces
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: x-spaces.searchspaces
      with:
        query: tools.query
        state: tools.state
        max_results: tools.max_results
      outputParameters:
      - type: object
        mapping: $.
    - name: x-get-space-id
      description: X Get Space by ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: x-spaces.getspacesbyid
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: x-get-space-ticket-buyers
      description: X Get Space Ticket Buyers
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: x-spaces.getspacesbuyers
      with:
        id: tools.id
        pagination_token: tools.pagination_token
        max_results: tools.max_results
      outputParameters:
      - type: object
        mapping: $.
    - name: x-get-space-posts
      description: X Get Space Posts
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: x-spaces.getspacesposts
      with:
        id: tools.id
        max_results: tools.max_results
      outputParameters:
      - type: object
        mapping: $.