openapi: 3.0.3
info:
version: 1.0.0
title: OmniServe Analytics 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
paths:
/analytics/pages:
get:
tags:
- Analytics Pages
summary: Get Analytics Pages
description: 'This endpoint enables you to get the list of all analytics pages available to your
company.
**Note:** Returns pages like inbox, slas, agents, and in-chat-survey.
'
operationId: getAnalyticsPages
responses:
'200':
description: Pages list
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: inbox
examples:
default:
value:
data:
- id: 1
name: inbox
- id: 2
name: slas
- id: 3
name: agents
- id: 4
name: in-chat-survey
'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}/widgets:
get:
tags:
- Analytics Pages
summary: Get Page Widgets
description: 'This endpoint enables you to list available widgets for a specific analytics page.
'
operationId: getPageWidgets
parameters:
- name: page_name
in: path
description: Analytics page identifier (e.g., inbox, slas, agents)
required: true
schema:
type: string
example: inbox
responses:
'200':
description: Widgets metadata
content:
application/json:
schema:
type: object
properties:
widgets_names:
type: array
items:
type: string
example:
- Inbox Overview
- Engagements Volume
company_time_zone:
type: integer
example: 3
page_name:
type: string
example: inbox
'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}/filters:
get:
tags:
- Analytics Pages
summary: Get Page Filters
description: 'This endpoint enables you to get filter definitions for a specific analytics page.
'
operationId: getPageFilters
parameters:
- name: page_name
in: path
description: Analytics page identifier
required: true
schema:
type: string
example: inbox
responses:
'200':
description: Filters list
content:
application/json:
schema:
type: object
properties:
filters:
type: array
items:
type: object
properties:
filter_key:
type: string
example: data_sources
filter_label:
type: string
example: Data Sources
values:
type: array
items:
type: object
properties:
label:
type: string
example: twitter
value:
type: integer
example: 1
page_name:
type: string
example: inbox
'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}/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\n\
Aggregates 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\n\
Time-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
# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lucidya-ltd/refs/heads/main/openapi/lucidya-ltd-omniserve-analytics-api-openapi.yml