Gladly REST API — Conversations

naftiko: 1.0.0-alpha2
info:
  label: Gladly REST API — Conversations
  description: Gladly REST API — Conversations. 19 operations. Self-contained Naftiko capability covering the Conversations
    business surface of the Gladly Customer Service Platform.
  tags:
  - Gladly
  - Conversations
  - Customer Service
  created: '2026-05-24'
  modified: '2026-05-24'
binds:
- namespace: env
  keys:
    GLADLY_ORGANIZATION: GLADLY_ORGANIZATION
    GLADLY_AGENT_EMAIL: GLADLY_AGENT_EMAIL
    GLADLY_API_TOKEN: GLADLY_API_TOKEN
capability:
  consumes:
  - type: http
    namespace: gladly-conversations
    baseUri: https://{{env.GLADLY_ORGANIZATION}}.gladly.com
    description: Gladly REST API — Conversations business capability.
    resources:
    - name: api-v1-customers-customerId-conversations
      path: /api/v1/customers/{customerId}/conversations
      operations:
      - name: getConversations
        method: GET
        description: Get Conversations for Customer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: customerId
          in: path
          type: string
          required: true
          description: Id of the customer to get all conversations for
    - name: api-v1-conversations-conversationId
      path: /api/v1/conversations/{conversationId}
      operations:
      - name: getConversation
        method: GET
        description: Get Conversation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversationId
          in: path
          type: string
          required: true
          description: Id of the conversation to get
      - name: patchConversation
        method: PATCH
        description: Update Conversation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversationId
          in: path
          type: string
          required: true
          description: Id of the conversation
        - name: body
          in: body
          type: object
          required: true
          description: Request body (JSON).
    - name: api-v1-conversation-items
      path: /api/v1/conversation-items
      operations:
      - name: createItem
        method: POST
        description: Create Item
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: true
          description: Request body (JSON).
    - name: api-v1-conversation-items-itemId
      path: /api/v1/conversation-items/{itemId}
      operations:
      - name: getItem
        method: GET
        description: Get Item
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: itemId
          in: path
          type: string
          required: true
          description: 'id of the conversation item

            '
      - name: deleteItem
        method: DELETE
        description: Delete Item
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: itemId
          in: path
          type: string
          required: true
          description: 'Id of the item to be deleted.

            '
    - name: api-v1-conversation-items-itemId-media-recording
      path: /api/v1/conversation-items/{itemId}/media/recording
      operations:
      - name: getMedia
        method: GET
        description: Get Media
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: itemId
          in: path
          type: string
          required: true
          description: 'id of the conversation item

            '
    - name: api-v1-conversation-items-itemId-voice-transcript
      path: /api/v1/conversation-items/{itemId}/voice-transcript
      operations:
      - name: getVoiceTranscript
        method: GET
        description: Get Voice Transcript
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: itemId
          in: path
          type: string
          required: true
          description: 'id of the conversation item

            '
    - name: api-v1-conversation-items-itemId-attachments-attachmentId
      path: /api/v1/conversation-items/{itemId}/attachments/{attachmentId}
      operations:
      - name: getAttachment
        method: GET
        description: Get Attachment
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: itemId
          in: path
          type: string
          required: true
          description: 'Id of the conversation item that contains the attachment.

            '
        - name: attachmentId
          in: path
          type: string
          required: true
          description: 'Id of the attachment to retrieve.

            '
    - name: api-v1-customers-customerId-conversation-items
      path: /api/v1/customers/{customerId}/conversation-items
      operations:
      - name: createCustomerItem
        method: POST
        description: Create Item for Customer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: customerId
          in: path
          type: string
          required: true
          description: 'Id of the customer associated with this item.


            You can look up the id using the [Find customers](index.html#tag/Customers) API.

            '
        - name: body
          in: body
          type: object
          required: true
          description: Request body (JSON).
    - name: api-v1-customers-customerId-conversation-items-itemId
      path: /api/v1/customers/{customerId}/conversation-items/{itemId}
      operations:
      - name: deleteCustomerItem
        method: DELETE
        description: Delete Item for Customer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: customerId
          in: path
          type: string
          required: true
          description: 'Id of the customer associated with this item.


            You can look up the id using the [Find customers](index.html#tag/Customers) API.

            '
        - name: itemId
          in: path
          type: string
          required: true
          description: 'Id of the item to be deleted.

            '
    - name: api-v1-conversations-conversationId-items
      path: /api/v1/conversations/{conversationId}/items
      operations:
      - name: getConversationItems
        method: GET
        description: List Items in Conversation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversationId
          in: path
          type: string
          required: true
          description: Id of the conversation to get the timeline for
        - name: sessionId
          in: query
          type: string
          required: false
          description: Return only items whose `sessionId` matches the given value.
    - name: api-v1-conversations-conversationId-topics
      path: /api/v1/conversations/{conversationId}/topics
      operations:
      - name: addTopicToConversation
        method: POST
        description: Add Topics to Conversation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversationId
          in: path
          type: string
          required: true
          description: 'Id of the conversation.

            '
        - name: body
          in: body
          type: object
          required: true
          description: Request body (JSON).
    - name: api-v1-conversations-conversationId-topics-topicId
      path: /api/v1/conversations/{conversationId}/topics/{topicId}
      operations:
      - name: deleteTopicFromConversation
        method: DELETE
        description: Delete Topic From Conversation
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversationId
          in: path
          type: string
          required: true
          description: 'Id of the conversation.

            '
        - name: topicId
          in: path
          type: string
          required: true
          description: 'Id of topic to be deleted from conversation.

            '
    - name: api-v1-customer-history-customerId-conversations-conversatio
      path: /api/v1/customer-history/{customerId}/conversations/{conversationId}/custom-attributes
      operations:
      - name: post-api-v1-customer-history-customerId-conversations-conversatio
        method: POST
        description: Add or Remove Freeform Topic
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: customerId
          in: path
          type: string
          required: true
          description: 'Id of the customer.

            '
        - name: conversationId
          in: path
          type: string
          required: true
          description: 'Id of the conversation.

            '
        - name: body
          in: body
          type: object
          required: true
          description: Request body (JSON).
    - name: api-v1-conversations-conversationId-notes
      path: /api/v1/conversations/{conversationId}/notes
      operations:
      - name: addNoteToConversation
        method: POST
        description: Add Note
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversationId
          in: path
          type: string
          required: true
          description: 'Id of the conversation.

            '
        - name: body
          in: body
          type: object
          required: true
          description: Request body (JSON).
    - name: api-v1-conversations-conversationId-notes-noteId
      path: /api/v1/conversations/{conversationId}/notes/{noteId}
      operations:
      - name: getNoteFromConversation
        method: GET
        description: Get Note
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: conversationId
          in: path
          type: string
          required: true
          description: 'id of the conversation

            '
        - name: noteId
          in: path
          type: string
          required: true
          description: 'id of the note

            '
    - name: api-v1-conversation-items-itemId-reply
      path: /api/v1/conversation-items/{itemId}/reply
      operations:
      - name: replyToMessage
        method: POST
        description: Reply to Message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: itemId
          in: path
          type: string
          required: true
          description: 'id of the conversation item

            '
        - name: body
          in: body
          type: object
          required: true
          description: Request body (JSON).
    - name: api-v1-conversation-items-itemId-redact
      path: /api/v1/conversation-items/{itemId}/redact
      operations:
      - name: redactContent
        method: POST
        description: Redact Conversation Item
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: itemId
          in: path
          type: string
          required: true
          description: 'id of the conversation item

            '
        - name: body
          in: body
          type: object
          required: true
          description: Request body (JSON).
    authentication:
      type: basic
      username: '{{env.GLADLY_AGENT_EMAIL}}'
      password: '{{env.GLADLY_API_TOKEN}}'
  exposes:
  - type: rest
    namespace: gladly-conversations-rest
    port: 8080
    description: REST adapter for Gladly Conversations.
    resources:
    - path: /v1/api/v1/customers/{customerId}/conversations
      name: api-v1-customers-customerId-conversations
      description: REST surface for api-v1-customers-customerId-conversations.
      operations:
      - method: GET
        name: getConversations
        description: Get Conversations for Customer
        call: gladly-conversations.getConversations
        with:
          customerId: rest.path.customerId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversations/{conversationId}
      name: api-v1-conversations-conversationId
      description: REST surface for api-v1-conversations-conversationId.
      operations:
      - method: GET
        name: getConversation
        description: Get Conversation
        call: gladly-conversations.getConversation
        with:
          conversationId: rest.path.conversationId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversations/{conversationId}
      name: api-v1-conversations-conversationId
      description: REST surface for api-v1-conversations-conversationId.
      operations:
      - method: PATCH
        name: patchConversation
        description: Update Conversation
        call: gladly-conversations.patchConversation
        with:
          conversationId: rest.path.conversationId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversation-items
      name: api-v1-conversation-items
      description: REST surface for api-v1-conversation-items.
      operations:
      - method: POST
        name: createItem
        description: Create Item
        call: gladly-conversations.createItem
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversation-items/{itemId}
      name: api-v1-conversation-items-itemId
      description: REST surface for api-v1-conversation-items-itemId.
      operations:
      - method: GET
        name: getItem
        description: Get Item
        call: gladly-conversations.getItem
        with:
          itemId: rest.path.itemId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversation-items/{itemId}
      name: api-v1-conversation-items-itemId
      description: REST surface for api-v1-conversation-items-itemId.
      operations:
      - method: DELETE
        name: deleteItem
        description: Delete Item
        call: gladly-conversations.deleteItem
        with:
          itemId: rest.path.itemId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversation-items/{itemId}/media/recording
      name: api-v1-conversation-items-itemId-media-recording
      description: REST surface for api-v1-conversation-items-itemId-media-recording.
      operations:
      - method: GET
        name: getMedia
        description: Get Media
        call: gladly-conversations.getMedia
        with:
          itemId: rest.path.itemId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversation-items/{itemId}/voice-transcript
      name: api-v1-conversation-items-itemId-voice-transcript
      description: REST surface for api-v1-conversation-items-itemId-voice-transcript.
      operations:
      - method: GET
        name: getVoiceTranscript
        description: Get Voice Transcript
        call: gladly-conversations.getVoiceTranscript
        with:
          itemId: rest.path.itemId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversation-items/{itemId}/attachments/{attachmentId}
      name: api-v1-conversation-items-itemId-attachments-attachmentId
      description: REST surface for api-v1-conversation-items-itemId-attachments-attachmentId.
      operations:
      - method: GET
        name: getAttachment
        description: Get Attachment
        call: gladly-conversations.getAttachment
        with:
          itemId: rest.path.itemId
          attachmentId: rest.path.attachmentId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/customers/{customerId}/conversation-items
      name: api-v1-customers-customerId-conversation-items
      description: REST surface for api-v1-customers-customerId-conversation-items.
      operations:
      - method: POST
        name: createCustomerItem
        description: Create Item for Customer
        call: gladly-conversations.createCustomerItem
        with:
          customerId: rest.path.customerId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/customers/{customerId}/conversation-items/{itemId}
      name: api-v1-customers-customerId-conversation-items-itemId
      description: REST surface for api-v1-customers-customerId-conversation-items-itemId.
      operations:
      - method: DELETE
        name: deleteCustomerItem
        description: Delete Item for Customer
        call: gladly-conversations.deleteCustomerItem
        with:
          customerId: rest.path.customerId
          itemId: rest.path.itemId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversations/{conversationId}/items
      name: api-v1-conversations-conversationId-items
      description: REST surface for api-v1-conversations-conversationId-items.
      operations:
      - method: GET
        name: getConversationItems
        description: List Items in Conversation
        call: gladly-conversations.getConversationItems
        with:
          conversationId: rest.path.conversationId
          sessionId: rest.query.sessionId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversations/{conversationId}/topics
      name: api-v1-conversations-conversationId-topics
      description: REST surface for api-v1-conversations-conversationId-topics.
      operations:
      - method: POST
        name: addTopicToConversation
        description: Add Topics to Conversation
        call: gladly-conversations.addTopicToConversation
        with:
          conversationId: rest.path.conversationId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversations/{conversationId}/topics/{topicId}
      name: api-v1-conversations-conversationId-topics-topicId
      description: REST surface for api-v1-conversations-conversationId-topics-topicId.
      operations:
      - method: DELETE
        name: deleteTopicFromConversation
        description: Delete Topic From Conversation
        call: gladly-conversations.deleteTopicFromConversation
        with:
          conversationId: rest.path.conversationId
          topicId: rest.path.topicId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/customer-history/{customerId}/conversations/{conversationId}/custom-attributes
      name: api-v1-customer-history-customerId-conversations-conversatio
      description: REST surface for api-v1-customer-history-customerId-conversations-conversatio.
      operations:
      - method: POST
        name: post-api-v1-customer-history-customerId-conversations-conversatio
        description: Add or Remove Freeform Topic
        call: gladly-conversations.post-api-v1-customer-history-customerId-conversations-conversatio
        with:
          customerId: rest.path.customerId
          conversationId: rest.path.conversationId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversations/{conversationId}/notes
      name: api-v1-conversations-conversationId-notes
      description: REST surface for api-v1-conversations-conversationId-notes.
      operations:
      - method: POST
        name: addNoteToConversation
        description: Add Note
        call: gladly-conversations.addNoteToConversation
        with:
          conversationId: rest.path.conversationId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversations/{conversationId}/notes/{noteId}
      name: api-v1-conversations-conversationId-notes-noteId
      description: REST surface for api-v1-conversations-conversationId-notes-noteId.
      operations:
      - method: GET
        name: getNoteFromConversation
        description: Get Note
        call: gladly-conversations.getNoteFromConversation
        with:
          conversationId: rest.path.conversationId
          noteId: rest.path.noteId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversation-items/{itemId}/reply
      name: api-v1-conversation-items-itemId-reply
      description: REST surface for api-v1-conversation-items-itemId-reply.
      operations:
      - method: POST
        name: replyToMessage
        description: Reply to Message
        call: gladly-conversations.replyToMessage
        with:
          itemId: rest.path.itemId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v1/conversation-items/{itemId}/redact
      name: api-v1-conversation-items-itemId-redact
      description: REST surface for api-v1-conversation-items-itemId-redact.
      operations:
      - method: POST
        name: redactContent
        description: Redact Conversation Item
        call: gladly-conversations.redactContent
        with:
          itemId: rest.path.itemId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: gladly-conversations-mcp
    port: 9090
    transport: http
    description: MCP adapter for Gladly Conversations.
    tools:
    - name: gladly-getConversations
      description: Get Conversations for Customer
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gladly-conversations.getConversations
      with:
        customerId: tools.customerId
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-getConversation
      description: Get Conversation
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gladly-conversations.getConversation
      with:
        conversationId: tools.conversationId
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-patchConversation
      description: Update Conversation
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gladly-conversations.patchConversation
      with:
        conversationId: tools.conversationId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-createItem
      description: Create Item
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gladly-conversations.createItem
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-getItem
      description: Get Item
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gladly-conversations.getItem
      with:
        itemId: tools.itemId
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-deleteItem
      description: Delete Item
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: gladly-conversations.deleteItem
      with:
        itemId: tools.itemId
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-getMedia
      description: Get Media
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gladly-conversations.getMedia
      with:
        itemId: tools.itemId
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-getVoiceTranscript
      description: Get Voice Transcript
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gladly-conversations.getVoiceTranscript
      with:
        itemId: tools.itemId
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-getAttachment
      description: Get Attachment
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gladly-conversations.getAttachment
      with:
        itemId: tools.itemId
        attachmentId: tools.attachmentId
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-createCustomerItem
      description: Create Item for Customer
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gladly-conversations.createCustomerItem
      with:
        customerId: tools.customerId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-deleteCustomerItem
      description: Delete Item for Customer
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: gladly-conversations.deleteCustomerItem
      with:
        customerId: tools.customerId
        itemId: tools.itemId
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-getConversationItems
      description: List Items in Conversation
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gladly-conversations.getConversationItems
      with:
        conversationId: tools.conversationId
        sessionId: tools.sessionId
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-addTopicToConversation
      description: Add Topics to Conversation
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gladly-conversations.addTopicToConversation
      with:
        conversationId: tools.conversationId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-deleteTopicFromConversation
      description: Delete Topic From Conversation
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: gladly-conversations.deleteTopicFromConversation
      with:
        conversationId: tools.conversationId
        topicId: tools.topicId
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-post-api-v1-customer-history-customerId-conversations-con
      description: Add or Remove Freeform Topic
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gladly-conversations.post-api-v1-customer-history-customerId-conversations-conversatio
      with:
        customerId: tools.customerId
        conversationId: tools.conversationId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-addNoteToConversation
      description: Add Note
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gladly-conversations.addNoteToConversation
      with:
        conversationId: tools.conversationId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-getNoteFromConversation
      description: Get Note
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gladly-conversations.getNoteFromConversation
      with:
        conversationId: tools.conversationId
        noteId: tools.noteId
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-replyToMessage
      description: Reply to Message
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gladly-conversations.replyToMessage
      with:
        itemId: tools.itemId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: gladly-redactContent
      description: Redact Conversation Item
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gladly-conversations.redactContent
      with:
        itemId: tools.itemId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.