openapi: 3.0.3
info:
  title: Lorikeet Conversations Knowledge 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: Knowledge
  description: Ingest and manage knowledge sources the agent reasons over.
paths:
  /knowledge/sources:
    get:
      operationId: listKnowledgeSources
      tags:
      - Knowledge
      summary: List knowledge sources
      responses:
        '200':
          description: Configured knowledge sources.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KnowledgeSource'
    post:
      operationId: ingestKnowledgeSource
      tags:
      - Knowledge
      summary: Ingest a knowledge source
      description: Submit a document, URL, or help-center article for ingestion into the knowledge base the agent reasons over. Ingestion is asynchronous; poll the returned source for status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestKnowledgeRequest'
      responses:
        '202':
          description: Ingestion accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeSource'
  /knowledge/sources/{source_id}:
    parameters:
    - name: source_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getKnowledgeSource
      tags:
      - Knowledge
      summary: Retrieve a knowledge source
      responses:
        '200':
          description: The knowledge source and its ingestion status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeSource'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteKnowledgeSource
      tags:
      - Knowledge
      summary: Delete a knowledge source
      responses:
        '204':
          description: Knowledge source deleted.
components:
  schemas:
    IngestKnowledgeRequest:
      type: object
      properties:
        type:
          type: string
          enum:
          - url
          - document
          - article
        url:
          type: string
          format: uri
          description: Source URL when `type` is `url` or `article`.
        title:
          type: string
        content:
          type: string
          description: Inline content when `type` is `document`.
    KnowledgeSource:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - url
          - document
          - article
        title:
          type: string
        status:
          type: string
          enum:
          - pending
          - processing
          - ready
          - failed
          description: Asynchronous ingestion status.
        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.'