openapi: 3.0.3
info:
  title: Lorikeet Conversations Webhooks 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: Webhooks
  description: Manage webhook subscriptions and receive Lorikeet events.
paths:
  /webhooks:
    get:
      operationId: listWebhooks
      tags:
      - Webhooks
      summary: List webhook subscriptions
      responses:
        '200':
          description: Registered webhook subscriptions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookSubscription'
    post:
      operationId: createWebhook
      tags:
      - Webhooks
      summary: Create a webhook subscription
      description: Register an endpoint to receive Lorikeet events. Deliveries are signed so the receiver can cryptographically verify them (HMAC) before acting.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: Webhook subscription created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
  /webhooks/{webhook_id}:
    parameters:
    - name: webhook_id
      in: path
      required: true
      schema:
        type: string
    delete:
      operationId: deleteWebhook
      tags:
      - Webhooks
      summary: Delete a webhook subscription
      responses:
        '204':
          description: Webhook subscription deleted.
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    EventType:
      type: string
      enum:
      - conversation.created
      - conversation.updated
      - conversation.resolved
      - conversation.escalated
      - message.created
      description: Lorikeet event types delivered to webhook subscribers.
    WebhookSubscription:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventType'
        created_at:
          type: string
          format: date-time
    CreateWebhookRequest:
      type: object
      required:
      - url
      - events
      properties:
        url:
          type: string
          format: uri
          description: HTTPS endpoint that will receive signed event deliveries.
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventType'
        secret:
          type: string
          description: Shared secret used to compute the HMAC signature on deliveries so you can verify authenticity before acting.
    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.'