X API v2 — Chat

naftiko: 1.0.0-alpha2
info:
  label: X API v2 — Chat
  description: 'X API v2 — Chat. 16 operations. Lead operation: X Get Chat Conversations. Self-contained Naftiko capability
    covering one Twitter business surface.'
  tags:
  - Twitter
  - Chat
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    TWITTER_API_KEY: TWITTER_API_KEY
capability:
  consumes:
  - type: http
    namespace: x-chat
    baseUri: https://api.x.com
    description: X API v2 — Chat business capability. Self-contained, no shared references.
    resources:
    - name: 2-chat-conversations
      path: /2/chat/conversations
      operations:
      - name: getchatconversations
        method: GET
        description: X Get Chat Conversations
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: max_results
          in: query
          type: integer
          description: Maximum number of conversations to return.
        - name: pagination_token
          in: query
          type: string
          description: Token for pagination to retrieve the next page of results.
    - name: 2-chat-conversations-group
      path: /2/chat/conversations/group
      operations:
      - name: createchatconversation
        method: POST
        description: X Create Chat Group Conversation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: 2-chat-conversations-group-initialize
      path: /2/chat/conversations/group/initialize
      operations:
      - name: initializechatgroup
        method: POST
        description: X Initialize Chat Group
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 2-chat-conversations-id
      path: /2/chat/conversations/{id}
      operations:
      - name: getchatconversation
        method: GET
        description: X Get Chat Conversation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The recipient's user ID for a 1:1 conversation, or a group conversation ID (prefixed with 'g').
          required: true
        - name: max_results
          in: query
          type: integer
          description: Maximum number of message events to return.
        - name: pagination_token
          in: query
          type: string
          description: Token for pagination to retrieve the next page of results.
    - name: 2-chat-conversations-id-keys
      path: /2/chat/conversations/{id}/keys
      operations:
      - name: initializechatconversationkeys
        method: POST
        description: X Initialize Conversation Keys
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The recipient's user ID for a 1:1 conversation, or a group conversation ID (prefixed with 'g').
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: 2-chat-conversations-id-members
      path: /2/chat/conversations/{id}/members
      operations:
      - name: addchatgroupmembers
        method: POST
        description: X Add Members to a Chat Group Conversation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The Chat group conversation ID.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: 2-chat-conversations-id-messages
      path: /2/chat/conversations/{id}/messages
      operations:
      - name: sendchatmessage
        method: POST
        description: X Send Chat Message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The recipient's user ID for a 1:1 conversation, or a group conversation ID (prefixed with 'g').
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: 2-chat-conversations-id-read
      path: /2/chat/conversations/{id}/read
      operations:
      - name: markchatconversationread
        method: POST
        description: X Mark Conversation as Read
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The recipient's user ID for a 1:1 conversation, or a group conversation ID (prefixed with 'g').
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: 2-chat-conversations-id-typing
      path: /2/chat/conversations/{id}/typing
      operations:
      - name: sendchattypingindicator
        method: POST
        description: X Send Typing Indicator
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The recipient's user ID for a 1:1 conversation, or a group conversation ID (prefixed with 'g').
          required: true
    - name: 2-chat-media-upload-initialize
      path: /2/chat/media/upload/initialize
      operations:
      - name: chatmediauploadinitialize
        method: POST
        description: X Initialize Chat Media Upload
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: 2-chat-media-upload-id-append
      path: /2/chat/media/upload/{id}/append
      operations:
      - name: chatmediauploadappend
        method: POST
        description: X Append Chat Media Upload
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The session/resume id from initialize.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: 2-chat-media-upload-id-finalize
      path: /2/chat/media/upload/{id}/finalize
      operations:
      - name: chatmediauploadfinalize
        method: POST
        description: X Finalize Chat Media Upload
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The session/resume id from initialize.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: 2-chat-media-id-media_hash_key
      path: /2/chat/media/{id}/{media_hash_key}
      operations:
      - name: chatmediadownload
        method: GET
        description: X Download Chat Media
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The recipient's user ID for a 1:1 conversation, or a group conversation ID (prefixed with 'g').
          required: true
        - name: media_hash_key
          in: path
          type: string
          description: The media hash key returned from the upload initialize step.
          required: true
    - name: 2-users-public_keys
      path: /2/users/public_keys
      operations:
      - name: getuserspublickeys
        method: GET
        description: X Get Public Keys for Multiple Users
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ids
          in: query
          type: array
          description: A list of User IDs, comma-separated. You can specify up to 100 IDs.
          required: true
    - name: 2-users-id-public_keys
      path: /2/users/{id}/public_keys
      operations:
      - name: getuserspublickey
        method: GET
        description: X Get User Public Keys
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the User to lookup.
          required: true
      - name: adduserpublickey
        method: POST
        description: X Add Public Key
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the requesting user.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    authentication:
      type: bearer
      token: '{{env.TWITTER_API_KEY}}'
  exposes:
  - type: rest
    namespace: x-chat-rest
    port: 8080
    description: REST adapter for X API v2 — Chat. One Spectral-compliant resource per consumed operation, prefixed with /v1.
    resources:
    - path: /v1/2/chat/conversations
      name: 2-chat-conversations
      description: REST surface for 2-chat-conversations.
      operations:
      - method: GET
        name: getchatconversations
        description: X Get Chat Conversations
        call: x-chat.getchatconversations
        with:
          max_results: rest.max_results
          pagination_token: rest.pagination_token
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/chat/conversations/group
      name: 2-chat-conversations-group
      description: REST surface for 2-chat-conversations-group.
      operations:
      - method: POST
        name: createchatconversation
        description: X Create Chat Group Conversation
        call: x-chat.createchatconversation
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/chat/conversations/group/initialize
      name: 2-chat-conversations-group-initialize
      description: REST surface for 2-chat-conversations-group-initialize.
      operations:
      - method: POST
        name: initializechatgroup
        description: X Initialize Chat Group
        call: x-chat.initializechatgroup
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/chat/conversations/{id}
      name: 2-chat-conversations-id
      description: REST surface for 2-chat-conversations-id.
      operations:
      - method: GET
        name: getchatconversation
        description: X Get Chat Conversation
        call: x-chat.getchatconversation
        with:
          id: rest.id
          max_results: rest.max_results
          pagination_token: rest.pagination_token
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/chat/conversations/{id}/keys
      name: 2-chat-conversations-id-keys
      description: REST surface for 2-chat-conversations-id-keys.
      operations:
      - method: POST
        name: initializechatconversationkeys
        description: X Initialize Conversation Keys
        call: x-chat.initializechatconversationkeys
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/chat/conversations/{id}/members
      name: 2-chat-conversations-id-members
      description: REST surface for 2-chat-conversations-id-members.
      operations:
      - method: POST
        name: addchatgroupmembers
        description: X Add Members to a Chat Group Conversation
        call: x-chat.addchatgroupmembers
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/chat/conversations/{id}/messages
      name: 2-chat-conversations-id-messages
      description: REST surface for 2-chat-conversations-id-messages.
      operations:
      - method: POST
        name: sendchatmessage
        description: X Send Chat Message
        call: x-chat.sendchatmessage
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/chat/conversations/{id}/read
      name: 2-chat-conversations-id-read
      description: REST surface for 2-chat-conversations-id-read.
      operations:
      - method: POST
        name: markchatconversationread
        description: X Mark Conversation as Read
        call: x-chat.markchatconversationread
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/chat/conversations/{id}/typing
      name: 2-chat-conversations-id-typing
      description: REST surface for 2-chat-conversations-id-typing.
      operations:
      - method: POST
        name: sendchattypingindicator
        description: X Send Typing Indicator
        call: x-chat.sendchattypingindicator
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/chat/media/upload/initialize
      name: 2-chat-media-upload-initialize
      description: REST surface for 2-chat-media-upload-initialize.
      operations:
      - method: POST
        name: chatmediauploadinitialize
        description: X Initialize Chat Media Upload
        call: x-chat.chatmediauploadinitialize
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/chat/media/upload/{id}/append
      name: 2-chat-media-upload-id-append
      description: REST surface for 2-chat-media-upload-id-append.
      operations:
      - method: POST
        name: chatmediauploadappend
        description: X Append Chat Media Upload
        call: x-chat.chatmediauploadappend
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/chat/media/upload/{id}/finalize
      name: 2-chat-media-upload-id-finalize
      description: REST surface for 2-chat-media-upload-id-finalize.
      operations:
      - method: POST
        name: chatmediauploadfinalize
        description: X Finalize Chat Media Upload
        call: x-chat.chatmediauploadfinalize
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/chat/media/{id}/{media-hash-key}
      name: 2-chat-media-id-media-hash-key
      description: REST surface for 2-chat-media-id-media_hash_key.
      operations:
      - method: GET
        name: chatmediadownload
        description: X Download Chat Media
        call: x-chat.chatmediadownload
        with:
          id: rest.id
          media_hash_key: rest.media_hash_key
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/users/public-keys
      name: 2-users-public-keys
      description: REST surface for 2-users-public_keys.
      operations:
      - method: GET
        name: getuserspublickeys
        description: X Get Public Keys for Multiple Users
        call: x-chat.getuserspublickeys
        with:
          ids: rest.ids
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/2/users/{id}/public-keys
      name: 2-users-id-public-keys
      description: REST surface for 2-users-id-public_keys.
      operations:
      - method: GET
        name: getuserspublickey
        description: X Get User Public Keys
        call: x-chat.getuserspublickey
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: adduserpublickey
        description: X Add Public Key
        call: x-chat.adduserpublickey
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: x-chat-mcp
    port: 9090
    transport: http
    description: MCP adapter for X API v2 — Chat. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: x-get-chat-conversations
      description: X Get Chat Conversations
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: x-chat.getchatconversations
      with:
        max_results: tools.max_results
        pagination_token: tools.pagination_token
      outputParameters:
      - type: object
        mapping: $.
    - name: x-create-chat-group-conversation
      description: X Create Chat Group Conversation
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: x-chat.createchatconversation
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: x-initialize-chat-group
      description: X Initialize Chat Group
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: x-chat.initializechatgroup
      outputParameters:
      - type: object
        mapping: $.
    - name: x-get-chat-conversation
      description: X Get Chat Conversation
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: x-chat.getchatconversation
      with:
        id: tools.id
        max_results: tools.max_results
        pagination_token: tools.pagination_token
      outputParameters:
      - type: object
        mapping: $.
    - name: x-initialize-conversation-keys
      description: X Initialize Conversation Keys
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: x-chat.initializechatconversationkeys
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: x-add-members-chat-group
      description: X Add Members to a Chat Group Conversation
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: x-chat.addchatgroupmembers
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: x-send-chat-message
      description: X Send Chat Message
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: x-chat.sendchatmessage
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: x-mark-conversation-read
      description: X Mark Conversation as Read
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: x-chat.markchatconversationread
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: x-send-typing-indicator
      description: X Send Typing Indicator
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: x-chat.sendchattypingindicator
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: x-initialize-chat-media-upload
      description: X Initialize Chat Media Upload
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: x-chat.chatmediauploadinitialize
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: x-append-chat-media-upload
      description: X Append Chat Media Upload
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: x-chat.chatmediauploadappend
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: x-finalize-chat-media-upload
      description: X Finalize Chat Media Upload
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: x-chat.chatmediauploadfinalize
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: x-download-chat-media
      description: X Download Chat Media
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: x-chat.chatmediadownload
      with:
        id: tools.id
        media_hash_key: tools.media_hash_key
      outputParameters:
      - type: object
        mapping: $.
    - name: x-get-public-keys-multiple
      description: X Get Public Keys for Multiple Users
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: x-chat.getuserspublickeys
      with:
        ids: tools.ids
      outputParameters:
      - type: object
        mapping: $.
    - name: x-get-user-public-keys
      description: X Get User Public Keys
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: x-chat.getuserspublickey
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: x-add-public-key
      description: X Add Public Key
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: x-chat.adduserpublickey
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.