openapi: 3.2.0
info:
  title: Arthur Conversations Messages API
  version: 2.0.0
  description: Arthur Conversations API - the conversations surface of the Arthur API v2, the UK property management platform from Arthur Online (an Aareon company). Derived operation-for-operation from the provider's public Postman Documenter collection at https://developer.arthuronline.co.uk/. Every request is scoped to an Arthur entity via the mandatory X-EntityID header and authorised with an OAuth 2.0 Authorization Code access token.
  contact:
    name: Arthur Online API Support
    url: https://support.arthuronline.co.uk/
  termsOfService: https://www.arthuronline.co.uk/terms-and-conditions/
  x-derived-from: collections/arthur-online.postman_collection.json
  x-derived-by: API Evangelist enrichment pipeline
  x-derived-date: '2026-07-26'
servers:
- url: https://api.arthuronline.co.uk/v2
  description: Arthur API v2 production
security:
- arthurOAuth: []
tags:
- name: Messages
paths:
  /conversations/{conversation_id}/messages:
    get:
      operationId: listMessagesRelatedToConversation
      summary: List Messages Related To Conversation
      tags:
      - Messages
      parameters:
      - name: conversation_id
        in: path
        required: true
        description: Arthur conversation id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/Direction'
      description: This retrieves a list of messages related to a conversation id .
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                status: 200
                data:
                - id: 1
                  conversation_id: 2
                  title: subject
                  message: Hello
                  sent_by_me: true
                  model: Property
                  model_id: 3
                  parent_id: 4
                  is_group: false
                  total_replies: 2
                  created_by:
                    id: 5
                    name: Brian Acton
                    group: manager
                  recipients:
                  - id: 6
                    full_name: Dan Dudley
                    is_read: false
                  sent_by:
                    id: 5
                    name: Brian Acton
                  created: '2020-06-04T14:29:14+01:00'
                  modified: '2020-06-04T14:29:14+01:00'
                - id: 12
                  conversation_id: 2
                  title: subject
                  message: Hello
                  sent_by_me: true
                  model: Property
                  model_id: 3
                  parent_id: 1
                  is_group: false
                  total_replies: 2
                  created_by:
                    id: 5
                    name: Brian Acton
                    group: manager
                  recipients:
                  - id: 6
                    full_name: Dan Dudley
                    is_read: false
                  sent_by:
                    id: 6
                    name: Dan Dudley
                  created: '2020-06-04T14:22:13+01:00'
                  modified: '2020-06-04T14:29:14+01:00'
                pagination:
                  page: 1
                  current: 2
                  count: 2
                  pageCount: 1
                  limit: 20
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: addMessagesRelatedToConversation
      summary: Add Messages Related To Conversation
      tags:
      - Messages
      parameters:
      - name: conversation_id
        in: path
        required: true
        description: Arthur conversation id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      - $ref: '#/components/parameters/Strict'
      description: "Use this endpoint to add a new message related to a  conversation . The API will return the saved data.\n\nSupported Fields \n The following fields are supported for the request body\n\nField \n Example \n Type \n Required? \n\nmessage \n It's done \n String \n Yes"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  example: It's done
              required:
              - message
            example:
              message: No problem
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  data:
                    type: object
              example:
                status: 200
                data:
                  id: 123
                  conversation_id: 123
                  title: Conversation Subject
                  message: No problem
                  model: Property
                  model_id: 123
                  parent_id: 1234
                  is_group: false
                  total_replies: 1234
                  created_by:
                    id: 123
                    name: Ronnie Wilson
                    group: manager
                  recipients:
                  - id: 123
                    full_name: Ronnie Wilson
                    entity_id: 123
                    is_read: true
                  - id: 123
                    full_name: Ronnie Wilson
                    entity_id: 123
                    is_read: false
                  sent_by:
                    id: 123
                    name: Ronnie Wilson
                  created: '2020-06-02T14:29:14+01:00'
                  modified: '2020-06-02T14:29:14+01:00'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /conversations/{conversation_id}/messages/{message_id}:
    get:
      operationId: viewMessageRelatedToConversation
      summary: View Message Related To Conversation
      tags:
      - Messages
      parameters:
      - name: conversation_id
        in: path
        required: true
        description: Arthur conversation id.
        schema:
          type: integer
      - name: message_id
        in: path
        required: true
        description: Arthur message id.
        schema:
          type: integer
      - $ref: '#/components/parameters/EntityId'
      description: 'This API endpoint retrieves the details of a single message, identified by its unique  message_id .


        Use this endpoint to view the specific details of a message within a conversation.'
      responses:
        '200':
          description: The request was completed successfully without errors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                status: 200
                data:
                - id: 1
                  conversation_id: 2
                  title: subject
                  message: Hello
                  sent_by_me: true
                  model: Property
                  model_id: 3
                  parent_id: 4
                  is_group: false
                  total_replies: 2
                  created_by:
                    id: 5
                    name: Brian Acton
                    group: manager
                  recipients:
                  - id: 6
                    full_name: Dan Dudley
                    is_read: false
                  sent_by:
                    id: 5
                    name: Brian Acton
                  created: '2020-06-04T14:29:14+01:00'
                  modified: '2020-06-04T14:29:14+01:00'
                pagination:
                  page: 1
                  current: 2
                  count: 2
                  pageCount: 1
                  limit: 20
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    Direction:
      name: direction
      in: query
      required: false
      description: Sort direction.
      schema:
        type: string
        enum:
        - ASC
        - DESC
    Sort:
      name: sort
      in: query
      required: false
      description: Field to sort the collection by.
      schema:
        type: string
    Strict:
      name: strict
      in: query
      required: false
      description: When true, abort the request instead of auto-creating an unknown Simple type. POST and PUT only.
      schema:
        type: boolean
    EntityId:
      name: X-EntityID
      in: header
      required: true
      description: The Arthur entity (account) the request is scoped to. Mandatory on every API call.
      schema:
        type: string
    Page:
      name: page
      in: query
      required: false
      description: Page number, between 1 and the total number of pages.
      schema:
        type: integer
        minimum: 1
    Limit:
      name: limit
      in: query
      required: false
      description: Items per page, between 1 and 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The request was sent to a location that does not exist in the API.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid or expired access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: expired_token
            message: This token has expired.
  schemas:
    Pagination:
      type: object
      description: Pagination block returned on every list response.
      properties:
        page:
          type: integer
        current:
          type: integer
        count:
          type: integer
        pageCount:
          type: integer
        limit:
          type: integer
    Error:
      type: object
      description: Arthur error envelope.
      properties:
        status:
          type: integer
        error:
          type: string
          description: Machine-readable error code, e.g. expired_token.
        message:
          type: string
  securitySchemes:
    arthurOAuth:
      type: oauth2
      description: OAuth 2.0 Authorization Code flow. Access tokens are valid for 14 days; refresh tokens for 21 days. Register an application in Arthur Settings > OAuth Applications to obtain a client_id and client_secret.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.arthuronline.co.uk/oauth/authorize
          tokenUrl: https://auth.arthuronline.co.uk/oauth/token
          refreshUrl: https://auth.arthuronline.co.uk/oauth/token
          scopes: {}