openapi: 3.2.0
info:
  version: 1.0.0
  title: OmniServe Analytics Analytics Jobs API
  description: "Complete API collection for Lucidya OmniServe Analytics Endpoints. This API provides access to \nanalytics data for engagement monitoring, CSAT surveys, and reporting capabilities.\n\nFeatures include:\n- Analytics pages and widgets discovery\n- Job-based analytics data retrieval\n- CSAT survey analytics\n- Reference data access (agents, teams, data sources)\n"
  contact:
    name: API Support
    email: support@lucidya.com
    url: https://lucidya.com
  license:
    url: https://opensource.org/licenses/MIT
    name: MIT
servers:
- url: https://api.lucidya.com/public_api/omniserve
  description: Production Server
security:
- OmniserveToken: []
tags:
- name: Analytics Jobs
  description: Endpoints for creating and retrieving analytics jobs
paths:
  /analytics/{page_name}/create:
    post:
      tags:
      - Analytics Jobs
      summary: Create Analytics Job
      description: 'This endpoint enables you to create an analytics job for a page and returns a job_id for retrieving results.

        '
      operationId: createAnalyticsJob
      parameters:
      - name: page_name
        in: path
        description: Analytics page identifier
        required: true
        schema:
          type: string
          example: inbox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                widgets_names:
                  type: array
                  description: Array of widget names to fetch
                  items:
                    type: string
                  example:
                  - Inbox Overview
                  - Engagements Volume
                start_date:
                  type: integer
                  description: Unix timestamp for start date
                  format: int64
                  example: 1640995200
                end_date:
                  type: integer
                  description: Unix timestamp for end date
                  format: int64
                  example: 1641081600
                filters:
                  type: object
                  description: Filter object (optional)
                  example: {}
              required:
              - widgets_names
              - start_date
              - end_date
            examples:
              inboxFilters:
                summary: Apply filters - inbox page
                value:
                  widgets_names:
                  - Inbox Overview
                  - Engagements Volume
                  start_date: 1727395200
                  end_date: 1728000000
                  monitors: 101,102
                  filters:
                    data_sources: twitter,facebook
                    engagement_types: posts,direct_messages,emails
                    routings_ids: '5'
                    tags_ids: 10,12
                    exact_match: false
                    untagged_engagements: false
              slasFilters:
                summary: Apply filters - slas page
                value:
                  widgets_names:
                  - SLAs Overview
                  - Breach Rate
                  start_date: 1727395200
                  end_date: 1728000000
                  monitors: '101'
                  filters:
                    data_sources: twitter
                    engagement_types: posts,direct_messages
                    slas_ids: 7,9
                    sla_type: time_to_complete,first_response_time,next_response_time,unassigned_response_time
                    tags_ids: 10,12
                    exact_match: false
                    untagged_engagements: false
              agentsFilters:
                summary: Apply filters - agents page
                value:
                  widgets_names:
                  - Agents Performance
                  - Agents Workload
                  start_date: 1727395200
                  end_date: 1728000000
                  monitors: '101'
                  filters:
                    data_sources: facebook
                    engagement_types: posts,direct_messages
                    assignees_ids: 201,202
                    exact_match: false
                    untagged_engagements: false
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                start_date:
                  type: integer
                  format: int64
                  example: 1760313600
                end_date:
                  type: integer
                  format: int64
                  example: 1760918399
                monitors:
                  type: string
                  description: Comma-separated monitor IDs
                  example: 45930,45922
                filters:
                  type: string
                  description: URL-encoded JSON string of filters
                  example: '%7B%22data_sources%22:%22twitter,facebook,instagram,whatsapp,email,livechat%22,%22engagement_types%22:%22posts,direct_messages%22,%22routings_ids%22:%2256,57,62%22,%22tags_ids%22:%2218,2,1,21,28,27%22,%22exact_match%22:false,%22untagged_engagements%22:false%7D'
              required:
              - start_date
              - end_date
            examples:
              rawConcatenated:
                summary: Raw form-encoded body
                value: product_id=10&start_date=1760313600&end_date=1760918399&monitors=45930,45922&filters=%7B%22data_sources%22:%22twitter,facebook,instagram,whatsapp,email,livechat%22,%22engagement_types%22:%22posts,direct_messages%22,%22routings_ids%22:%2256,57,62%22,%22tags_ids%22:%2218,2,1,21,28,27%22,%22exact_match%22:false,%22untagged_engagements%22:false%7D
      responses:
        '200':
          description: Job created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      job_id:
                        type: string
                        format: uuid
                        example: 550e8400-e29b-41d4-a716-446655440000
                      page_name:
                        type: string
                        example: inbox
                      widgets_names:
                        type: array
                        items:
                          type: string
                        example:
                        - Inbox Overview
                        - Engagements Volume
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '410':
          $ref: '#/components/responses/Gone'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
      security:
      - OmniserveToken: []
      servers:
      - url: https://api.lucidya.com/public_api/omniserve
        description: Production Server
  /analytics/{page_name}/index:
    get:
      tags:
      - Analytics Jobs
      summary: Get Analytics Results
      description: "This endpoint enables you to get the results of a previously created analytics job.\n\n## Response Structure\n\nThe response contains:\n- **dataAvailable**: Boolean indicating if all widget results are ready (true when complete)\n- **widget_data**: Object keyed by widget name, where each value is the widget's payload\n\n## Inbox Page Widgets\n\n### Inbox Overview\nAggregates counts per data source (twitter, twitter_dm, instagram, etc.):\n- **total_engagements**: Total found items in the period\n- **total_completed**: Count of completed engagements\n- **total_replied**: Count of replied engagements\n\n### Engagements Volume\n- **total_datasource_count**: Breakdown by engagement type (direct_message, comments_mentions, email_messages)\n- **engagements_overtime/posts_over_time**: Time-series data per source and engagement type\n\n### Agents Performance\n- **agents_performance**: Per-source array of agent performance objects containing:\n  - agent_id: Agent identifier\n  - assigned: Number of assigned engagements\n  - completed: Number of completed engagements\n\n### Average SLAs\nContains current_period and previous_period data with aggregated sums and counts for:\n- **first_response_time**: Time to first agent response\n- **next_response_time**: Time between subsequent responses\n- **time_to_complete**: Total time to close the engagement\n- **unassigned_response_time**: Time spent unassigned (TUT)\n- **handling_time**: Calculated as time_to_complete - unassigned_response_time (for completed interactions only)\n\n### Data Sources\n- **data_source_distribution**: Total engagements per data source\n\n### Completion Reason\n- **completion_reasons**: Per-source arrays of completion reasons with:\n  - id: Reason identifier\n  - reason_en: Reason text in English\n  - reason_ar: Reason text in Arabic\n  - value: Count of engagements with this reason\n\n### Engagement Distribution Over Routings\nPer-source routing arrays containing:\n- routing_id: Routing identifier\n- value: Number of engagements\n\n### Tags Distribution Over Engagements\n- **tags_performance**: Arrays per source with tag label, color, and usage count\n\n### Tags Usage Over Time\n- **total_datasource_count**: Breakdown by engagement type\n- **engagement_tags_usage_overtime**: Time-series tag usage per source\n\n### Engagers Activity (Unique)\n- **result**: 2D heatmap matrix arrays showing activity distribution\n- **min_value/max_value**: Range of values in the heatmap\n\n### Engagements Completed Overtime\n- **total_datasource_count**: Total completed by engagement type\n- **completed_engagements_overtime**: Time-series of completed engagements\n\n### Engagements Completed By Teams\n- **engagements_completed_by_teams**: Per-source arrays with team_id and completion count\n\n---\n\n## SLAs Page Widgets\n\n### Average SLAs\nSame structure as Inbox page - contains current_period and previous_period aggregated sums and counts for all SLA metrics.\n\n### SLAs Overview\nHigh-level KPI summary:\n- **breach_rate_percentage**: Percentage of SLA breaches\n- **met_sla_count**: Total number of interactions that met SLA\n- **breached_sla_count**: Total number of SLA breaches\n\n### SLAs Time Distribution\nBucketed counts showing duration distribution (in minutes) for SLA metrics:\n- **time_to_complete**: Bucketed time ranges (e.g., 0-30, 31-60, 61-120, 121+)\n- **first_response_time**: Bucketed response times (e.g., 0-5, 6-15, 16+)\n- **next_response_time**: Bucketed time ranges\n- **unassigned_response_time**: Bucketed response times\n- **Note**: Time values are returned from APIs in seconds and need to be converted to minutes or hours\n\nEach bucket contains a label and value (count)\n\n### Average SLAs Overview\nPeriod averages (in minutes) for all SLA metrics:\n- first_response_time\n- next_response_time\n- time_to_complete\n- unassigned_response_time\n- handling_time\n\n### Hits Activity\nTime-series data of interactions that met SLA (hits):\n- **total_count**: Total hits in the period\n- **over_time**: Array of timestamp and count pairs\n\n### Misses Activity\nTime-series data of interactions that breached SLA (misses):\n- **total_count**: Total misses in the period\n- **over_time**: Array of timestamp and count pairs\n\n---\n\n## Agents Page Widgets\n\n### Overview\nHigh-level agent metrics per data source:\n- **total_assigned_engagements**: Total number of assigned engagements\n- **assigned_public_engagements**: Public engagements assigned count\n- **assigned_dm_engagements**: Direct message engagements assigned count\n- **assigned_email_engagements**: Email engagements assigned count\n- **manual_assigned_engagements**: Manually assigned engagement count\n- **auto_assigned_engagements**: Auto-assigned engagement count\n- **total_unique_contacts**: Number of unique contacts\n- **avg_engagements_per_contact**: Average engagements per contact\n\n### Agent Inbox Performance\nAgent performance metrics over time:\n- **agent_inbox_performance**: Per-source performance data\n  - total_assigned: Total assigned to agents\n  - posts_over_time: Time-series arrays for assigned and completed\n  - total_completed: Total completed count\n- **agent_inbox_legends**: Summary legend with name-value pairs for assigned and completed\n\n### Agent CSAT Score Overtime\nCustomer satisfaction scores over time:\n- **csat_scores_overtime**: Per-source CSAT data\n  - csat_scores_over_time: Array of date and scores (5-point scale array)\n  - csat_scores_piechart: Distribution breakdown (e.g., csat_neutral, csat_positive, csat_negative)\n\n### Agents Performance\nIndividual agent performance metrics:\n- **agents_performance**: Per-source array of agent objects\n  - agent_id: Agent identifier\n  - assigned: Number of assigned engagements\n  - completed: Number of completed engagements\n\n### Agents CSAT Score\nAgent-specific CSAT metrics per data source:\n- **data**: Object containing:\n  - total_csat: Total CSAT score\n  - scores: Array of score distributions (csat_neutral, csat_positive, csat_negative)\n\n### Agent Status Overview\nCurrent agent status distribution:\n- **data**: Array of status objects with:\n  - status: Agent status (e.g., available, busy, offline)\n  - total_sum: Count of agents in this status\n- **count**: Total number of agents\n\n### Agent Status Summary\nDetailed agent status information:\n- **data**: Array of agent status details\n\n### Agents Distribution\nDistribution of engagements across agents:\n- **engagement_distribution_over_agents**: Per-source distribution\n  - total_engagements: Total engagement count\n  - agents: Array of agent-specific distributions\n\n### Engagements Analytics\nComprehensive engagement analytics per data source:\n- **total_replied_engagements**: Count of replied engagements\n- **total_completed_engagements**: Count of completed engagements\n- **reopens**: Number of reopened engagements\n- **avg_handle_time**: Average handling time with value and count\n- **total_in_chat_survey_sent**: Number of in-chat surveys sent\n- **total_in_chat_survey_responses**: Number of survey responses received\n- **total_tags_on_engagements**: Total tags applied to engagements\n- **engagements_with_notes**: Count of engagements with notes\n"
      parameters:
      - name: job_id
        in: query
        description: Job identifier returned from the create job endpoint
        required: true
        schema:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
      - name: page_name
        in: path
        description: Analytics page identifier
        required: true
        schema:
          type: string
          example: inbox
      responses:
        '200':
          description: Job results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      dataAvailable:
                        type: boolean
                        description: Indicates whether all requested widgets finished processing; true when results are complete.
                        example: true
                      widget_data:
                        type: object
                        description: Map of widget name to its payload; each widget has its own structure (see example descriptions).
                        additionalProperties:
                          type: object
                          properties:
                            value:
                              type: number
                              description: Example KPI value for simple metric widgets; for complex widgets, see examples.
                              example: 150
                            trend:
                              type: string
                              description: Example trend direction for KPI widgets (e.g., up/down/flat).
                              example: up
                            percentage_change:
                              type: number
                              description: Example percentage change for KPI widgets.
                              example: 12.5
              examples:
                Inbox Job Results:
                  summary: Inbox page job results (condensed)
                  description: "Key meanings:\n- data: Top-level response wrapper.\n- dataAvailable: Boolean indicating if all widget results are ready.\n- widget_data: Object keyed by widget name; each value is the widget payload.\n- Inbox Overview: Aggregates counts per data source (e.g., twitter, twitter_dm, instagram)\n  - total_engagements: Total found items in period\n  - total_completed: Completed engagements count\n  - total_replied: Replied engagements count\n- Engagements Volume:\n  - total_datasource_count: Breakdown by engagement type (direct_message, comments_mentions, email_messages)\n  - engagements_overtime/posts_over_time: Time-series per source and type\n- Agents Performance:\n  - agents_performance: Per source array of agent performance objects { agent_id, assigned, completed }\n- Average SLAs:\n  - current_period/previous_period: Aggregated sums and counts for SLA metrics (first_response_time, next_response_time, time_to_complete, unassigned_response_time, handling_time)\n  - handling_time: Calculated as time_to_complete - unassigned_response_time (TUT), for completed interactions only\n- Data Sources:\n  - data_source_distribution: Total engagements per source\n- Completion Reason:\n  - completion_reasons: Per source arrays of reasons with { id, reason_en, reason_ar, value }\n- Engagement Distribution Over Routings:\n  - per-source routings arrays with { routing_id, value }\n- Tags Distribution Over Engagements / Tags Usage Over Time:\n  - tags_performance arrays and time-series usage per source\n- Engagers Activity (Unique):\n  - result: 2D heatmap matrix arrays; min_value/max_value show range\n"
                  value:
                    data:
                      dataAvailable: true
                      widget_data:
                        Inbox Overview:
                          twitter_dm:
                            total_engagements: 79
                            total_completed: 64
                            total_replied: 38
                          twitter:
                            total_engagements: 119
                            total_completed: 29
                            total_replied: 55
                          instagram:
                            total_engagements: 77
                            total_completed: 27
                        Engagements Volume:
                          total_datasource_count:
                          - name: direct_message
                            value: 152
                          - name: comments_mentions
                            value: 215
                          - name: email_messages
                            value: 5
                        Agents Performance:
                          agents_performance:
                            twitter_dm:
                            - agent_id: 1341
                              assigned: 17
                              completed: 16
                        Average SLAs:
                          twitter_dm:
                            current_period:
                              first_response_time:
                                sum: 465343
                                count: 18
                              next_response_time:
                                sum: 1223
                                count: 3
                              time_to_complete:
                                sum: 1906072
                                count: 52
                              unassigned_response_time:
                                sum: 2143735
                                count: 61
                              handling_time:
                                sum: 156415
                                count: 51
                            previous_period:
                              first_response_time:
                                sum: 262023
                                count: 8
                              next_response_time:
                                sum: 50729817
                                count: 4
                              time_to_complete:
                                sum: 5281021
                                count: 48
                              unassigned_response_time:
                                sum: 4067691
                                count: 49
                              handling_time:
                                sum: 1213330
                                count: 48
                        Data Sources:
                          data_source_distribution:
                            twitter_dm:
                              total_engagements: 79
                            twitter:
                              total_engagements: 119
                        Engagement Distribution Over Routings:
                          engagement_distribution_over_routings:
                            twitter:
                              routings:
                              - routing_id: 62
                                value: 135
                        Tags Distribution Over Engagements:
                          tags_performance:
                            twitter_dm:
                            - label: Spam
                              color: '#FF3C2D'
                              value: 2
                        Tags Usage Over Time:
                          total_datasource_count:
                          - name: direct_message
                            value: 2
                          - name: comments_mentions
                            value: 1
                          engagement_tags_usage_overtime:
                            twitter_dm:
                              total_count: 2
                              posts_over_time:
                                direct_message:
                                - name: 1758412800
                                  value: 1
                        Engagers Activity (Unique):
                          engager_activity:
                            instagram:
                              result:
                              - - 0
                                - 0
                                - 0
                              - - 1
                                - 0
                                - 0
                              max_value: 6
                              min_value: 0
                        Completion Reason:
                          completion_reasons:
                            twitter:
                            - id: 1
                              reason_en: REASON_EN_VALUE
                              reason_ar: REASON_AR_VALUE
                              value: 26
                        Engagements Completed Overtime:
                          total_datasource_count:
                          - name: direct_message
                            value: 124
                          - name: comments_mentions
                            value: 64
                          completed_engagements_overtime:
                            twitter_dm:
                              total_count: 64
                              posts_over_time:
                                direct_message:
                                - name: 1758412800
                                  value: 12
                        Engagements Completed By Teams:
                          engagements_completed_by_teams:
                            twitter:
                            - team_id: 83
                              value: 15
                            twitter_dm:
                            - team_id: 83
                              value: 26
                SLAs Job Results:
                  summary: SLAs page job results (condensed)
                  description: "Key meanings (SLAs page):\n- data: Top-level response wrapper\n- dataAvailable: True when all widget results are ready\n- widget_data: Object keyed by widget name; value is the widget payload\n- Average SLAs:\n  - current_period/previous_period: Aggregated sums and counts for SLA metrics\n    (first_response_time, next_response_time, time_to_complete, unassigned_response_time, handling_time)\n  - handling_time: time_to_complete - unassigned_response_time (TUT), for completed interactions only\n- SLAs Overview: KPI summary such as met_sla_count, breached_sla_count, breach_rate_percentage\n- SLAs Time Distribution: Bucketed counts of durations (minutes) for SLA metrics (e.g., time_to_complete, first_response_time)\n- Average SLAs Overview: Period averages (minutes) for SLA metrics including handling_time\n- Hits Activity: Time-series of interactions that met SLA (hits)\n- Misses Activity: Time-series of interactions that breached SLA (misses)\n"
                  value:
                    data:
                      dataAvailable: true
                      widget_data:
                        Average SLAs:
                          twitter_dm:
                            current_period:
                              first_response_time:
                                sum: 465343
                                count: 18
                              next_response_time:
                                sum: 1223
                                count: 3
                              time_to_complete:
                                sum: 1906072
                                count: 52
                              unassigned_response_time:
                                sum: 2143735
                                count: 61
                              handling_time:
                                sum: 156415
                                count: 51
                            previous_period:
                              first_response_time:
                                sum: 262023
                                count: 8
                              next_response_time:
                                sum: 50729817
                                count: 4
                              time_to_complete:
                                sum: 5281021
                                count: 48
                              unassigned_response_time:
                                sum: 4067691
                                count: 49
                              handling_time:
                                sum: 1213330
                                count: 48
                        SLAs Overview:
                          breach_rate_percentage: 12.5
                          met_sla_count: 420
                          breached_sla_count: 60
                        SLAs Time Distribution:
                          time_distribution:
                            time_to_complete:
                            - label: 0-30
                              value: 120
                            - label: 31-60
                              value: 75
                            - label: 61-120
                              value: 40
                            - label: 121+
                              value: 18
                            first_response_time:
                            - label: 0-5
                              value: 210
                            - label: 6-15
                              value: 35
                            - label: 16+
                              value: 8
                        Average SLAs Overview:
                          description: Period averages for SLA metrics (in minutes).
                          averages:
                            first_response_time: 12.8
                            next_response_time: 7.5
                            time_to_complete: 85.4
                            unassigned_response_time: 34.2
                            handling_time: 51.2
                        Hits Activity:
                          description: Interactions that met SLA over time (hits)
                          hits_activity:
                            twitter_dm:
                              total_count: 40
                              over_time:
                              - name: 1758412800
                                value: 3
                              - name: 1758499200
                                value: 5
                        Misses Activity:
                          description: Interactions that breached SLA over time (misses)
                          misses_activity:
                            twitter_dm:
                              total_count: 12
                              over_time:
                              - name: 1758412800
                                value: 1
                              - name: 1758499200
                                value: 2
                Agents Job Results:
                  summary: Agents page job results (condensed)
                  value:
                    data:
                      dataAvailable: true
                      widget_data:
                        Overview:
                          twitter_dm:
                          - total_assigned_engagements: 0
                            assigned_public_engagements: 0
                            assigned_dm_engagements: 0
                            assigned_email_engagements: 0
                            manual_assigned_engagements: 0
                            auto_assigned_engagements: 0
                          total_unique_contacts: 0
                          avg_engagements_per_contact: 0
                        Agent Inbox Performance:
                          agent_inbox_performance:
                            twitter_dm:
                            - total_assigned: 0
                              posts_over_time:
                                assigned: []
                                completed: []
                              total_completed: 0
                          agent_inbox_legends:
                          - name: assigned
                            value: 0
                          - name: completed
                            value: 0
                        Agent CSAT Score Overtime:
                          csat_scores_overtime:
                            twitter:
                              csat_scores_over_time:
                              - date: 1727319600
                                scores:
                                - 0
                                - 0
                                - 0
                                - 0
                                - 0
                              csat_scores_piechart:
                              - name: csat_neutral
                                value: 0
                        Agents Performance:
                          agents_performance:
                            twitter_dm:
                            - agent_id: 1341
                              assigned: 0
                              completed: 0
                        Agents CSAT Score:
                          twitter_dm:
                          - data:
                              total_csat: 0
                              scores:
                              - name: csat_neutral
                                value: 0
                        Agent Status Overview:
                          data:
                          - status: available
                            total_sum: 0
                          count: 21
                        Agent Status Summary:
                          data: []
                        Agents Distribution:
                          engagement_distribution_over_agents:
                            twitter:
                            - total_engagements: 0
                              agents: []
                        Engagements Analytics:
                          twitter_dm:
                          - total_replied_engagements: 0
                            total_completed_engagements: 0
                            reopens: 0
                            avg_handle_time:
                              value: 0
                              count: 0
                            total_in_chat_survey_sent: 0
                            total_in_chat_survey_responses: 0
                            total_tags_on_engagements: 0
                            engagements_with_notes: 0
        '202':
          description: Processing (if applicable)
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '410':
          $ref: '#/components/responses/Gone'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
      security:
      - OmniserveToken: []
      servers:
      - url: https://api.lucidya.com/public_api/omniserve
        description: Production Server
components:
  responses:
    ValidationFailed:
      description: Unprocessable Entity - validation failed or missing required fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                status: 422
                message: Validation failed
    NotAcceptable:
      description: Not Acceptable - the requested format is not supported
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                status: 406
                message: Not acceptable
    BadRequest:
      description: Bad request - invalid input or validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                status: 400
                detail: Page_id is required
    RateLimited:
      description: Too many requests - rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                status: 429
                message: Rate limit exceeded
                retry_after: 60
    GatewayTimeout:
      description: Gateway Timeout - server took too long to respond
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                status: 504
                message: Gateway timeout
    Gone:
      description: Gone - the requested resource is no longer available
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                status: 410
                message: Resource gone
    NotFound:
      description: Not Found - the specified resource could not be found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                status: 404
                message: Resource not found
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                status: 500
                message: Internal server error
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                status: 403
                message: Access denied
    ServiceUnavailable:
      description: Service Unavailable - temporary server overload or maintenance
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                status: 503
                message: Service unavailable
    Unauthorized:
      description: Unauthorized - invalid or missing authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                status: 401
                message: Authentication required
    MethodNotAllowed:
      description: Method Not Allowed - HTTP method is not supported for this endpoint
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                status: 405
                message: Method not allowed
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: integer
              example: 400
            detail:
              type: string
              example: Page_id is required
        status:
          type: integer
          example: 400
        message:
          type: string
          example: Error message
        code:
          type: string
          example: ERROR_CODE
  securitySchemes:
    OmniserveToken:
      type: apiKey
      description: The API authorization token for the request
      name: luc-authorization
      in: header
      x-example: YOUR_API_TOKEN_HERE