openapi: 3.0.3
info:
  title: Lorikeet Conversations Messages API
  description: 'Programmatic surface for Lorikeet (Lorikeet CX), an AI customer support agent for complex and regulated businesses. The API centers on conversations (support tickets handled by the AI agent), messages within those conversations, webhook subscriptions and events, and knowledge ingestion.


    IMPORTANT (honesty note): Lorikeet''s authoritative API reference at docs.lorikeetcx.ai is gated behind a customer access code. The paths, schemas, and the base URL below are MODELED from Lorikeet''s public integration and security materials (synchronous scoped-credential API, inbound HMAC-signed webhooks, outbound async request/response, typed no-code "tools", and a per-step audit trail) and from common conventions for this class of AI support agent. They should be treated as a best-effort, plausible model - not field-verified contract - and reconciled against the official reference once access is available. Authentication is a Bearer API key.'
  version: 0.1.0-modeled
  contact:
    name: Lorikeet
    url: https://lorikeet.ai
  termsOfService: https://lorikeet.ai
servers:
- url: https://api.lorikeetcx.ai/v1
  description: Modeled base URL. The public site is lorikeet.ai and docs live at docs.lorikeetcx.ai; the exact API host is not published outside the gated reference.
security:
- bearerAuth: []
tags:
- name: Messages
  description: Post and list messages within a conversation.
paths:
  /conversations/{conversation_id}/messages:
    parameters:
    - $ref: '#/components/parameters/ConversationId'
    get:
      operationId: listMessages
      tags:
      - Messages
      summary: List messages
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of messages for the conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createMessage
      tags:
      - Messages
      summary: Post a message
      description: Append a message to a conversation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageRequest'
      responses:
        '201':
          description: Message created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
      description: Opaque pagination cursor from a prior response.
    ConversationId:
      name: conversation_id
      in: path
      required: true
      schema:
        type: string
  schemas:
    CreateMessageRequest:
      type: object
      required:
      - role
      - content
      properties:
        role:
          type: string
          enum:
          - end_user
          - agent
          description: Author of the message.
        content:
          type: string
    MessageList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        next_cursor:
          type: string
          nullable: true
    Message:
      type: object
      properties:
        id:
          type: string
        conversation_id:
          type: string
        role:
          type: string
          enum:
          - end_user
          - agent
          - system
        content:
          type: string
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            message:
              type: string
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer API key issued to your Lorikeet account. Send as `Authorization: Bearer <API_KEY>`. Lorikeet also supports OAuth2, JWT bearer, Basic, HMAC, and M2M flows for tool/action integrations into your systems; those secure Lorikeet''s outbound calls rather than this inbound management API.'