Lorikeet Conversations API

openapi: 3.2.0
info:
  title: Lorikeet Conversations API
  description: Programmatic surface for Lorikeet (Lorikeet CX), an AI customer support agent for complex and regulated businesses.
  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: Conversations
  description: Create, continue, and inspect AI-agent-handled support conversations.
paths:
  /conversations:
    post:
      operationId: createConversation
      tags:
      - Conversations
      summary: Create a conversation
      description: Start a new conversation (support ticket) for the Lorikeet AI agent to work. An optional first end-user message and end-user / context metadata can be supplied so the workflow orchestration layer can begin resolving immediately.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversationRequest'
      responses:
        '201':
          description: Conversation created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    get:
      operationId: listConversations
      tags:
      - Conversations
      summary: List conversations
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Cursor'
      - name: status
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ConversationStatus'
      responses:
        '200':
          description: A page of conversations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /conversations/{conversation_id}:
    parameters:
    - $ref: '#/components/parameters/ConversationId'
    get:
      operationId: getConversation
      tags:
      - Conversations
      summary: Retrieve a conversation
      description: Retrieve the current state of a conversation, including status, resolution, and whether it has been escalated to a human agent.
      responses:
        '200':
          description: The conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: continueConversation
      tags:
      - Conversations
      summary: Continue a conversation
      description: Continue an existing conversation by supplying a new end-user message. The agent advances its workflow and returns the updated conversation (including any new agent messages).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContinueConversationRequest'
      responses:
        '200':
          description: Updated conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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:
    CreateConversationRequest:
      type: object
      properties:
        end_user:
          $ref: '#/components/schemas/EndUser'
        message:
          type: string
          description: Optional first end-user message.
        channel:
          type: string
          description: Origin channel (e.g. chat, email, voice).
          enum:
          - chat
          - email
          - voice
        metadata:
          type: object
          additionalProperties: true
          description: Arbitrary context passed to the agent's workflows.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            message:
              type: string
    Conversation:
      type: object
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/ConversationStatus'
        channel:
          type: string
        end_user:
          $ref: '#/components/schemas/EndUser'
        resolution:
          type:
          - string
          - 'null'
          description: Summary of how the agent resolved the conversation, if resolved.
        escalated:
          type: boolean
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    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
    EndUser:
      type: object
      properties:
        id:
          type: string
          description: Your stable identifier for the end user.
        email:
          type: string
          format: email
        name:
          type: string
        attributes:
          type: object
          additionalProperties: true
          description: Traits used by workflows (e.g. plan, region, account state).
    ConversationStatus:
      type: string
      enum:
      - open
      - resolved
      - escalated
      - closed
      description: Lifecycle of a conversation. `escalated` indicates the agent handed off to a human per the workflow's escalation rules.
    ConversationList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
        next_cursor:
          type:
          - string
          - 'null'
    ContinueConversationRequest:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: New end-user message to advance the conversation.
        metadata:
          type: object
          additionalProperties: true
  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.'