openapi: 3.1.0
info:
  title: (Beta) Conversations authentication messages API
  version: 1.0.0
servers:
- url: https://api.moveworks.ai/rest/v1beta1
  description: US production server
- url: https://api.jp.moveworks.com/rest/v1beta1
  description: Japan production server
- url: https://api.uk.moveworks.com/rest/v1beta1
  description: UK production server
- url: https://api.prod4.us.moveworks.com/rest/v1beta1
  description: US Prod 4 production server
- url: https://api.prod3.us.moveworks.com/rest/v1beta1
  description: US Prod 3 production server
tags:
- name: messages
paths:
  /conversations/{conversation_id}/messages:
    get:
      operationId: list-conversation-messages
      summary: List conversation messages
      description: Retrieves all messages (both user and assistant) in a conversation in descending order by creation time (most recent first).
      tags:
      - messages
      parameters:
      - name: conversation_id
        in: path
        description: A base-62 identifier prefixed by a short resource type
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        description: Opaque cursor for pagination
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of messages to return (1-100)
        required: false
        schema:
          type: integer
          default: 20
      - name: Authorization
        in: header
        description: JWT bearer token authentication. Obtain an access token from the Moveworks auth endpoint and include it in the Authorization header as 'Bearer <token>'.
        required: true
        schema:
          type: string
      - name: Assistant-Name
        in: header
        description: The Moveworks assistant identifier that was configured for your organization.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListConversationMessagesResponse'
        '400':
          description: Bad request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidCursorErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        '403':
          description: Forbidden - Invalid assistant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
        '404':
          description: Not found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'
  /conversations/{conversation_id}/responses/{response_id}/messages:
    get:
      operationId: list-response-messages
      summary: List response messages
      description: Retrieves all messages associated with a specific response (both the user's input message and all assistant reply messages).
      tags:
      - messages
      parameters:
      - name: conversation_id
        in: path
        description: A base-62 identifier prefixed by a short resource type
        required: true
        schema:
          type: string
      - name: response_id
        in: path
        description: A base-62 identifier prefixed by a short resource type
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: JWT bearer token authentication. Obtain an access token from the Moveworks auth endpoint and include it in the Authorization header as 'Bearer <token>'.
        required: true
        schema:
          type: string
      - name: Assistant-Name
        in: header
        description: The Moveworks assistant identifier that was configured for your organization.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of messages for this response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponseMessagesResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        '403':
          description: Forbidden - Invalid assistant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
        '404':
          description: Not found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'
  /conversations/{conversation_id}/responses/{response_id}/messages/{message_id}/feedback:
    post:
      operationId: submit-feedback
      summary: Submit feedback
      description: 'Submits a feedback rating (helpful or unhelpful) for a specific assistant message.


        Use the `callback_id` from the message''s `feedback` field to indicate which rating is being submitted. The `callback_id` is an opaque token. Pass it back exactly as received.


        Optionally include `additional_feedback` for free-text comments.'
      tags:
      - messages
      parameters:
      - name: conversation_id
        in: path
        description: A base-62 identifier prefixed by a short resource type
        required: true
        schema:
          type: string
      - name: response_id
        in: path
        description: A base-62 identifier prefixed by a short resource type
        required: true
        schema:
          type: string
      - name: message_id
        in: path
        description: A base-62 identifier prefixed by a short resource type
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: JWT bearer token authentication. Obtain an access token from the Moveworks auth endpoint and include it in the Authorization header as 'Bearer <token>'.
        required: true
        schema:
          type: string
      - name: Assistant-Name
        in: header
        description: The Moveworks assistant identifier that was configured for your organization.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Feedback submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitFeedbackResponse'
        '400':
          description: Invalid request - the callback_id is malformed, does not match this message, or this message does not support feedback
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidFeedbackErrorResponse'
        '404':
          description: Not found - conversation, response, or message does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitFeedbackRequest'
components:
  schemas:
    MarkdownTextContent:
      type: object
      properties:
        text:
          type: string
          description: Raw markdown text content. Used when Minerva's chat response `is_commonmark` is not set.
      required:
      - text
      title: MarkdownTextContent
    RateLimitExceededErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/RateLimitExceededErrorResponseErrorCode'
        message:
          type: string
      required:
      - code
      - message
      title: RateLimitExceededErrorResponseError
    NotFoundErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/NotFoundErrorResponseError'
      required:
      - error
      description: Error response for resource not found
      title: NotFoundErrorResponse
    InvalidCursorErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/InvalidCursorErrorResponseError'
      required:
      - error
      description: Error response for invalid pagination cursor
      title: InvalidCursorErrorResponse
    CitationLocation:
      type: object
      properties:
        offset:
          type: integer
          description: Zero-based character position in the assistant message where the citation should be inserted
      description: '**Deprecated:** Use `Message.content_references` for positional data instead. This field will no longer be populated starting May 12, 2026 for both new and existing messages.'
      title: CitationLocation
    InvalidCursorErrorResponseErrorCode:
      type: string
      enum:
      - INVALID_CURSOR
      title: InvalidCursorErrorResponseErrorCode
    MessageFeedback:
      type: object
      properties:
        helpful:
          $ref: '#/components/schemas/FeedbackOption'
          description: Positive feedback option. Use this callback_id to rate the response as helpful.
        unhelpful:
          $ref: '#/components/schemas/FeedbackOption'
          description: Negative feedback option. Use this callback_id to rate the response as unhelpful.
      description: Feedback options available on an assistant message. When present, this message supports feedback and the callback IDs can be used to submit a rating.
      title: MessageFeedback
    SubmitFeedbackResponseStatus:
      type: string
      enum:
      - SUBMITTED
      description: Feedback submission status
      title: SubmitFeedbackResponseStatus
    Content:
      oneOf:
      - type: object
        properties:
          type:
            $ref: '#/components/schemas/PlainTextContentItemType'
            description: Content type discriminator
          plain_text:
            $ref: '#/components/schemas/PlainTextContent'
        required:
        - type
        - plain_text
        description: PLAIN_TEXT variant
      - type: object
        properties:
          type:
            $ref: '#/components/schemas/CommonmarkTextContentItemType'
            description: Content type discriminator
          commonmark_text:
            $ref: '#/components/schemas/CommonmarkTextContent'
        required:
        - type
        - commonmark_text
        description: COMMONMARK_TEXT variant
      - type: object
        properties:
          type:
            $ref: '#/components/schemas/MarkdownTextContentItemType'
            description: Content type discriminator
          markdown_text:
            $ref: '#/components/schemas/MarkdownTextContent'
        required:
        - type
        - markdown_text
        description: MARKDOWN_TEXT variant
      discriminator:
        propertyName: type
      description: Message content with type discriminator
      title: Content
    InvalidCursorErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/InvalidCursorErrorResponseErrorCode'
        message:
          type: string
      required:
      - code
      - message
      title: InvalidCursorErrorResponseError
    PlainTextContent:
      type: object
      properties:
        text:
          type: string
          description: Plain text content
      required:
      - text
      title: PlainTextContent
    UnauthorizedErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/UnauthorizedErrorResponseErrorCode'
        message:
          type: string
      required:
      - code
      - message
      title: UnauthorizedErrorResponseError
    UnauthorizedErrorResponseErrorCode:
      type: string
      enum:
      - UNAUTHORIZED
      title: UnauthorizedErrorResponseErrorCode
    ForbiddenErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ForbiddenErrorResponseErrorCode'
        message:
          type: string
      required:
      - code
      - message
      title: ForbiddenErrorResponseError
    Attribute:
      type: object
      properties:
        key:
          type: string
          description: Attribute name
        value:
          type: string
          description: Attribute value
      required:
      - key
      - value
      description: Key-value pair for citation display metadata. This is an opaque structure that contains rendering hints specific to each citation. Clients should not make assumptions about the keys or values present, as they may vary based on citation type and context.
      title: Attribute
    Message:
      type: object
      properties:
        message_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        conversation_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        response_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        actor:
          $ref: '#/components/schemas/ActorType'
        content:
          $ref: '#/components/schemas/Content'
        citations:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Citation'
          description: Unique citation references in the assistant message. Use `content_references` to determine where in the message text each citation is referenced.
        content_references:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CitationContentReference'
          description: Ordered positions in the message text where citations appear (ascending by offset). Each entry references a `Citation` via `citation_id`. Only populated on assistant messages.
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
        feedback:
          oneOf:
          - $ref: '#/components/schemas/MessageFeedback'
          - type: 'null'
          description: Feedback options for this message. Present only on final assistant messages that support feedback. Use the callback IDs to submit a rating via the feedback endpoint.
      required:
      - message_id
      - conversation_id
      - response_id
      - actor
      - content
      - created_at
      title: Message
    NotFoundErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/NotFoundErrorResponseErrorCode'
        message:
          type: string
      required:
      - code
      - message
      title: NotFoundErrorResponseError
    InvalidFeedbackErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/InvalidFeedbackErrorResponseError'
      required:
      - error
      description: Error response for invalid feedback submission
      title: InvalidFeedbackErrorResponse
    Display:
      type: object
      properties:
        title:
          $ref: '#/components/schemas/Content'
          description: Primary heading/identifier with type discriminator
        body:
          $ref: '#/components/schemas/Content'
          description: Body/description content with type discriminator
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
          description: Opaque key-value metadata for citation display. These attributes contain implementation-specific rendering hints and should be treated as a black-box by clients. The structure and values may vary between citations and should not be relied upon for business logic.
      title: Display
    Citation:
      type: object
      properties:
        citation_id:
          type: string
          description: 'Unique citation identifier (format: `cite_<base62>`). Use this to join with `content_references` on the Message object.'
        location:
          $ref: '#/components/schemas/CitationLocation'
          description: '**Deprecated:** Use `Message.content_references` for positional data instead. This field will no longer be populated starting May 12, 2026 for both new and existing messages.'
        url:
          type: string
          format: uri
          description: URL to the entity
        display:
          $ref: '#/components/schemas/Display'
      title: Citation
    InternalErrorResponseErrorCode:
      type: string
      enum:
      - INTERNAL_ERROR
      title: InternalErrorResponseErrorCode
    SubmitFeedbackResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/SubmitFeedbackResponseStatus'
          description: Feedback submission status
      required:
      - status
      title: SubmitFeedbackResponse
    Metadata:
      type: object
      properties:
        next_cursor:
          type:
          - string
          - 'null'
          description: Opaque cursor for next page (null if no more results)
      title: Metadata
    ForbiddenErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ForbiddenErrorResponseError'
      required:
      - error
      description: Error response for forbidden access
      title: ForbiddenErrorResponse
    ForbiddenErrorResponseErrorCode:
      type: string
      enum:
      - FORBIDDEN
      title: ForbiddenErrorResponseErrorCode
    ActorType:
      type: string
      enum:
      - USER
      - ASSISTANT
      description: Message actor type
      title: ActorType
    CitationContentReference:
      type: object
      properties:
        citation_id:
          type: string
          description: References `Citation.citation_id` to link this position to a citation entity.
        offset:
          type: integer
          description: Zero-based character position in the assistant message where the citation appears.
      required:
      - citation_id
      - offset
      title: CitationContentReference
    InvalidFeedbackErrorResponseErrorCode:
      type: string
      enum:
      - INVALID_REQUEST
      title: InvalidFeedbackErrorResponseErrorCode
    SubmitFeedbackRequest:
      type: object
      properties:
        callback_id:
          type: string
          description: The callback_id from either `feedback.helpful` or `feedback.unhelpful` on the message object. Determines which rating (helpful or unhelpful) is being submitted.
        additional_feedback:
          type: string
          description: Optional free-text feedback from the user. Use this to capture additional context about why the user rated the response this way.
      required:
      - callback_id
      title: SubmitFeedbackRequest
    FeedbackOption:
      type: object
      properties:
        callback_id:
          type: string
          description: Opaque callback identifier. Pass this value to the feedback endpoint to submit this rating.
      required:
      - callback_id
      title: FeedbackOption
    MarkdownTextContentItemType:
      type: string
      enum:
      - MARKDOWN_TEXT
      description: Content type discriminator
      title: MarkdownTextContentItemType
    CommonmarkTextContent:
      type: object
      properties:
        text:
          type: string
          description: Commonmark-formatted text content
      required:
      - text
      title: CommonmarkTextContent
    RateLimitExceededErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/RateLimitExceededErrorResponseError'
      required:
      - error
      description: Error response for rate limit exceeded
      title: RateLimitExceededErrorResponse
    RateLimitExceededErrorResponseErrorCode:
      type: string
      enum:
      - RATE_LIMIT_EXCEEDED
      title: RateLimitExceededErrorResponseErrorCode
    CommonmarkTextContentItemType:
      type: string
      enum:
      - COMMONMARK_TEXT
      description: Content type discriminator
      title: CommonmarkTextContentItemType
    PlainTextContentItemType:
      type: string
      enum:
      - PLAIN_TEXT
      description: Content type discriminator
      title: PlainTextContentItemType
    ListResponseMessagesResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: Array of messages for this response
      required:
      - messages
      title: ListResponseMessagesResponse
    NotFoundErrorResponseErrorCode:
      type: string
      enum:
      - NOT_FOUND
      title: NotFoundErrorResponseErrorCode
    InternalErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/InternalErrorResponseErrorCode'
        message:
          type: string
      required:
      - code
      - message
      title: InternalErrorResponseError
    InternalErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/InternalErrorResponseError'
      required:
      - error
      description: Error response for internal server error
      title: InternalErrorResponse
    InvalidFeedbackErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/InvalidFeedbackErrorResponseErrorCode'
        message:
          type: string
      required:
      - code
      - message
      title: InvalidFeedbackErrorResponseError
    UnauthorizedErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/UnauthorizedErrorResponseError'
      required:
      - error
      description: Error response for unauthorized access
      title: UnauthorizedErrorResponse
    ListConversationMessagesResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: Array of messages
        metadata:
          $ref: '#/components/schemas/Metadata'
          description: Metadata (pagination)
      required:
      - messages
      title: ListConversationMessagesResponse
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: JWT bearer token authentication. Obtain an access token from the Moveworks auth endpoint and include it in the Authorization header as 'Bearer <token>'.