Cayra Plaud Webhook API

openapi: 3.2.0
info:
  title: Cayra License Server Plaud Webhook API
  description: '# Cayra Chat Agent - License Management Server


    Centralized license management for on-premise deployments.


    ## Features


    - 🔑 License key generation (installation, update, trial)

    - ⏰ Dynamic expiry management (extend/shorten licenses)

    - 🔄 Activation tracking and monitoring

    - 💓 Heartbeat mechanism (1-hour intervals)

    - 📊 Audit logging for compliance

    - 🔐 JWT tokens with RSA-4096 encryption


    ## API Categories


    ### Admin Endpoints (Requires API Key)

    Manage licenses, view activations, update expiry dates.


    ### Client Endpoints (Public)

    Activate licenses, send heartbeats, check status.


    ## Authentication


    Admin endpoints require API key in header:

    ```

    X-Admin-API-Key: your-admin-key-here

    ```


    ## Security


    - 🔒 RSA-4096 asymmetric encryption

    - 🔐 JWT tokens for offline validation

    - 📝 Complete audit trail

    - 🛡️ Rate limiting (Phase 6)'
  contact:
    name: Cayra AI Team
    email: support@cayra.ai
  license:
    name: Proprietary
  version: 1.0.0
tags:
- name: plaud-webhook
paths:
  /api/v1/plaud/webhook:
    post:
      tags:
      - plaud-webhook
      summary: Receive Plaud transcript from Zapier
      description: 'Entry point for Plaud → Zapier → Cayra webhook events.


        Always returns 200 immediately after scheduling the VM forward in the

        background so Zapier never times out.'
      operationId: handle_plaud_webhook_api_v1_plaud_webhook_post
      parameters:
      - name: X-Plaud-Webhook-Secret
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Plaud-Webhook-Secret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaudWebhookPayload'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaudWebhookResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PlaudWebhookResponse:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        forwarded_to:
          anyOf:
          - type: string
          - type: 'null'
          title: Forwarded To
      type: object
      required:
      - status
      - message
      title: PlaudWebhookResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PlaudWebhookPayload:
      properties:
        user_email:
          type: string
          title: User Email
          description: Cayra account email (used to route to VM)
        transcript:
          type: string
          title: Transcript
          description: Full transcript text from Plaud
        summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary
          description: AI summary from Plaud
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: Recording title
        duration:
          anyOf:
          - type: number
          - type: 'null'
          title: Duration
          description: Duration in seconds
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
          description: Recording ISO-8601 timestamp
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
          description: Plaud file ID
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
          description: Detected language code
      type: object
      required:
      - user_email
      - transcript
      title: PlaudWebhookPayload
      description: "Fields Zapier maps from the Plaud \"Transcript & Summary Ready\" trigger.\n\nRequired:\n    user_email   – Cayra account email so we can route to the right VM.\n    transcript   – Full transcript text.\n\nOptional (all may be absent depending on Zapier field mapping):\n    summary      – AI summary generated by Plaud.\n    title        – Recording title / file name.\n    duration     – Recording duration in seconds.\n    created_at   – ISO-8601 timestamp when recording was made.\n    file_id      – Plaud file ID (for de-duplication).\n    language     – Detected language code (e.g. \"en\", \"tr\")."
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError