openapi: 3.0.3
info:
  title: Tidio OpenAPI (REST) Contacts Lyro API
  description: 'REST API for managing contacts, conversations, tickets, operators, and Lyro AI data sources. Requires Plus or Premium plan for full access; Lyro AI plan grants access to Lyro-specific endpoints. Authentication uses paired X-Tidio-Openapi-Client-Id and X-Tidio-Openapi-Client-Secret headers. Rate limits range from 10 requests per minute (entry plans) to 120 requests per minute (Premium).

    '
  version: '1'
  contact:
    name: Tidio Developer Support
    url: https://developers.tidio.com/support
  termsOfService: https://www.tidio.com/terms/
  license:
    name: Proprietary
    url: https://www.tidio.com/terms/
servers:
- url: https://api.tidio.co
  description: Tidio REST API
security:
- clientId: []
  clientSecret: []
tags:
- name: Lyro
  description: Lyro AI data sources and ticket answering
paths:
  /lyro/data-sources:
    get:
      operationId: getLyroDataSources
      tags:
      - Lyro
      summary: Get Lyro data sources
      description: 'Returns a paginated list of data sources used by the Lyro AI Agent. Supports filtering by kind (qa/folder) and parent_id.

        '
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          nullable: true
      - name: kind
        in: query
        required: false
        description: Filter by kind (qa or folder).
        schema:
          type: array
          items:
            type: string
            enum:
            - qa
            - folder
      - name: parent_id
        in: query
        required: false
        description: Filter by parent data source UUID.
        schema:
          type: string
          format: uuid
      - name: order
        in: query
        required: false
        description: Sort direction (asc or desc, defaults to desc).
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      responses:
        '200':
          description: Paginated list of Lyro data sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LyroDataSourceList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /lyro/data-sources/qa:
    post:
      operationId: createLyroQaDataSource
      tags:
      - Lyro
      summary: Create Lyro QA data source
      description: Creates a QA (question-answer) data source for the Lyro AI Agent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LyroQaCreate'
      responses:
        '201':
          description: QA data source created
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /lyro/data-sources/website:
    put:
      operationId: upsertLyroWebsiteDataSource
      tags:
      - Lyro
      summary: Upsert Lyro data source
      description: 'Uploads or updates an HTML-based data source for the Lyro AI Agent. If a source with the same URL exists, it is updated; otherwise a new one is created.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LyroWebsiteUpsert'
      responses:
        '200':
          description: Data source upserted
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /lyro/data-sources/website/scrape:
    post:
      operationId: scrapeWebsiteLyroDataSource
      tags:
      - Lyro
      summary: Add website as Lyro data source (scraping)
      description: 'Submits a website URL to be scraped and used as a knowledge data source for the Lyro AI Agent. Each URL must be unique per project.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  format: uri
                  description: Website URL to scrape.
      responses:
        '201':
          description: Website scraping initiated
        '409':
          description: URL already exists as a data source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /lyro/tickets:
    post:
      operationId: askLyroToAnswerTicket
      tags:
      - Lyro
      summary: Ask Lyro to answer ticket
      description: 'Asks Lyro AI to generate an answer for a ticket. Processing can take up to 40 seconds. Currently supports only the first message of a ticket.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LyroTicketRequest'
      responses:
        '200':
          description: Lyro answer generated (may be null if Lyro cannot answer)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message_content:
                    type: string
                    nullable: true
                    description: Answer generated by Lyro, or null if unable to answer.
        '409':
          description: Quota exceeded or Lyro disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    LyroWebsiteUpsert:
      type: object
      required:
      - url
      - title
      - content
      properties:
        url:
          type: string
          format: uri
        title:
          type: string
        content:
          type: string
          description: HTML content to be processed by Lyro.
    LyroTicketMessage:
      type: object
      required:
      - created_at
      - message_id
      - author_type
      - message_type
      - message_content
      properties:
        created_at:
          type: string
          format: date-time
        message_id:
          type: string
        author_type:
          type: string
          enum:
          - contact
        message_type:
          type: string
          enum:
          - public
        attachments:
          type: array
          items:
            type: string
            format: uri
        message_content:
          type: string
    PaginationMeta:
      type: object
      properties:
        cursor:
          type: string
          nullable: true
          description: Token for the next page; null when on the last page.
        limit:
          type: integer
    LyroDataSourceList:
      type: object
      properties:
        data_sources:
          type: array
          items:
            $ref: '#/components/schemas/LyroDataSource'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    LyroTicketRequest:
      type: object
      required:
      - ticket_id
      - subject
      - contact_email
      - contact_name
      - recipient_email
      - messages
      properties:
        ticket_id:
          type: integer
        subject:
          type: string
        contact_email:
          type: string
          format: email
        contact_name:
          type: string
        recipient_email:
          type: string
          format: email
        messages:
          type: array
          items:
            $ref: '#/components/schemas/LyroTicketMessage'
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
    ErrorItem:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    LyroDataSource:
      type: object
      properties:
        id:
          type: string
          format: uuid
        parent_id:
          type: string
          format: uuid
          nullable: true
        title:
          type: string
        type:
          type: string
          enum:
          - qa
          - website
          - zendesk_hc
          - external_html
          - pdf_file
        kind:
          type: string
          enum:
          - qa
          - folder
        origin:
          type: string
          enum:
          - manual
          - inbox
          - industry
          - website
          - csv_file
          - pdf_file
          - zendesk_hc
          - external_html
        status:
          type: string
          enum:
          - in progress
          - error
          - used
        used_by_lyro:
          type: boolean
        used_by_copilot:
          type: boolean
        sync_status:
          type: string
          enum:
          - in progress
          - error
          - success
          nullable: true
        content:
          type: string
          nullable: true
        source_url:
          type: string
          format: uri
          nullable: true
        skip_auto_sync:
          type: boolean
          nullable: true
        manual_sync_available_at:
          type: string
          format: date-time
          nullable: true
        next_auto_sync_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    LyroQaCreate:
      type: object
      required:
      - title
      - content
      properties:
        title:
          type: string
        content:
          type: string
  securitySchemes:
    clientId:
      type: apiKey
      in: header
      name: X-Tidio-Openapi-Client-Id
    clientSecret:
      type: apiKey
      in: header
      name: X-Tidio-Openapi-Client-Secret