Roark Analytics API

openapi: 3.2.0
info:
  title: Roark Analytics API
  description: The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform.
  version: 1.0.0
servers:
- description: Production
  url: https://api.roark.ai
security:
- Bearer: []
tags:
- name: Analytics
paths:
  /v1/analytics/schema:
    get:
      responses:
        '200':
          description: The analytics schema
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AnalyticsSchema'
                required:
                - data
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Rate limit error
              example:
                type: rate_limit
                code: too_many_requests
                message: Rate limit exceeded
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: getV1AnalyticsSchema
      tags:
      - Analytics
      summary: Get the analytics schema
      description: 'Lists what can go into an analytics query for this project: every metric by slug with its output

        type, default aggregation and the aggregations it supports; the measure types; the filter and

        breakdown types with the properties each accepts; and the custom call properties seen in the project.

        Read this first when building a query.'
  /v1/analytics/query:
    post:
      responses:
        '200':
          description: The query result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AnalyticsResult'
                required:
                - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Invalid or unsupported query
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: A metric was not found in this project
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Rate limit error
              example:
                type: rate_limit
                code: too_many_requests
                message: Rate limit exceeded
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: postV1AnalyticsQuery
      tags:
      - Analytics
      summary: Run an analytics query
      description: 'Aggregates metric values and conversation counts over a time window and returns one series per

        measure, with a total for the window and per-interval buckets. The same query a dashboard widget

        runs, without saving anything.


        - `measures`: what to aggregate. A METRIC measure names its metric by slug; CONVERSATION counts

        conversations; UPTIME reads health checks. The aggregation defaults by the metric''s output type.

        - `timeRange`: LAST n DAYS/WEEKS/MONTHS, a CALENDAR_ALIGNED period (TODAY, THIS_MONTH, ...), FIXED

        from/to, or SINCE. Defaults to the last 30 days; at most 731 days. Calendar periods and buckets

        align to `timezone` (IANA, default UTC).

        - `filters` apply to every measure; a measure''s own `filters` add to them.

        - `breakdown` on a measure returns one series per value (largest 50 kept).

        - `comparisonGroups` (2 to 5) run every measure once per named filter set;

        `comparisonMode: PREVIOUS_PERIOD` adds the preceding window''s values.


        Values are in the metric''s display units. A PASS_RATE is a 0 to 1 share; `sampleSize` 0 means no data.

        A query the analytics store cannot answer returns 400 naming the unsupported part.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsQuery'
components:
  schemas:
    AnalyticsSchema:
      type: object
      properties:
        metrics:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              slug:
                type: string
              name:
                type: string
              outputType:
                type: string
              isThreshold:
                type: boolean
              defaultAggregation:
                type: string
                enum:
                - COUNT
                - AVG
                - MIN
                - MAX
                - SUM
                - MEDIAN
                - PERCENTILE
                - PASS_RATE
              aggregations:
                type: array
                items:
                  type: string
                  enum:
                  - COUNT
                  - AVG
                  - MIN
                  - MAX
                  - SUM
                  - MEDIAN
                  - PERCENTILE
                  - PASS_RATE
            required:
            - id
            - slug
            - name
            - outputType
            - isThreshold
            - defaultAggregation
            - aggregations
        measureTypes:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - METRIC
                - CONVERSATION
                - UPTIME
              description:
                type: string
              aggregations:
                type: array
                items:
                  type: string
                  enum:
                  - COUNT
                  - AVG
                  - MIN
                  - MAX
                  - SUM
                  - MEDIAN
                  - PERCENTILE
                  - PASS_RATE
            required:
            - type
            - description
            - aggregations
        filters:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - METRIC_PROPERTY
                - CALL_PROPERTY
                - AGENT_PROPERTY
                - CALL_ID
                - MODALITY
                - DATASET
                - METRIC_VALUE
              description:
                type: string
              properties:
                type: array
                items:
                  type: object
                  properties:
                    property:
                      type: string
                    description:
                      type: string
                  required:
                  - property
                  - description
            required:
            - type
            - description
            - properties
        breakdowns:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - METRIC_PROPERTY
                - CALL_PROPERTY
                - AGENT_PROPERTY
                - DATASET
              description:
                type: string
            required:
            - type
            - description
        callProperties:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              valueType:
                type: string
              isSystem:
                type: boolean
            required:
            - name
            - valueType
            - isSystem
        operators:
          type: array
          items:
            type: string
            enum:
            - EQUALS
            - NOT_EQUALS
            - GREATER_THAN
            - GREATER_THAN_OR_EQUAL_TO
            - LESS_THAN
            - LESS_THAN_OR_EQUAL_TO
            - CONTAINS
            - STARTS_WITH
            - IS_SET
            - IS_NOT_SET
        intervals:
          type: array
          items:
            type: string
            enum:
            - HOUR
            - DAY
            - WEEK
            - MONTH
        displayTypes:
          type: array
          items:
            type: string
            enum:
            - LINE
            - NUMBER
            - RADAR
            - STACKED_BAR
            - TABLE
      required:
      - metrics
      - measureTypes
      - filters
      - breakdowns
      - callProperties
      - operators
      - intervals
      - displayTypes
      description: 'What can be queried in this project: metrics (by slug), measure types, filters, breakdowns.'
    AnalyticsQuery:
      type: object
      properties:
        measures:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - METRIC
                - CONVERSATION
                - UPTIME
                description: 'METRIC (default): a metric''s values. CONVERSATION: conversation counts. UPTIME: health-check outcomes.'
              metric:
                type: string
                minLength: 1
                description: The metric's slug (e.g. `task_completion`) or id. Required for METRIC.
              aggregation:
                type: string
                enum:
                - COUNT
                - AVG
                - MIN
                - MAX
                - SUM
                - MEDIAN
                - PERCENTILE
                - PASS_RATE
                description: 'Defaults by output type: AVG for numeric metrics, COUNT (split by value) for classification and text, PASS_RATE for thresholds and uptime, COUNT for conversations.'
              percentile:
                type: integer
                minimum: 0
                maximum: 100
                description: Required with PERCENTILE, e.g. 95.
              distinctBy:
                type: string
                enum:
                - NONE
                - CALL
                description: CALL (default for metrics) folds each conversation to one value first, so a long call does not outweigh a short one. NONE aggregates every value.
              nestedAggregation:
                type: string
                enum:
                - COUNT
                - AVG
                - MIN
                - MAX
                - SUM
                - MEDIAN
                - PERCENTILE
                - PASS_RATE
                description: How each conversation is folded when distinctBy is CALL. Defaults to SUM under SUM, else AVG.
              nestedAggregationPercentile:
                type: integer
                minimum: 0
                maximum: 100
              passOperator:
                type: string
                enum:
                - EQUALS
                - NOT_EQUALS
                - GREATER_THAN
                - GREATER_THAN_OR_EQUAL_TO
                - LESS_THAN
                - LESS_THAN_OR_EQUAL_TO
                - CONTAINS
                - STARTS_WITH
                - IS_SET
                - IS_NOT_SET
                description: 'PASS_RATE condition operator. Omit for a threshold metric: its own condition is used.'
              passValue:
                anyOf:
                - type: string
                - type: number
                - type: boolean
                description: PASS_RATE condition value, e.g. 4 or "resolved".
              breakdown:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                    - METRIC_PROPERTY
                    - CALL_PROPERTY
                    - AGENT_PROPERTY
                    - DATASET
                  property:
                    type: string
                    description: The property to split by. Required for CALL_PROPERTY and METRIC_PROPERTY.
                required:
                - type
                description: 'Split the measure into one series per value of this dimension (the largest 50 are returned). Ignored while comparisonGroups are set: each group is then one series.'
              filters:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                      - METRIC_PROPERTY
                      - CALL_PROPERTY
                      - AGENT_PROPERTY
                      - CALL_ID
                      - MODALITY
                      - DATASET
                      - METRIC_VALUE
                      description: What the filter narrows on. GET /v1/analytics/schema lists each type.
                    property:
                      type: string
                      description: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID.
                    operator:
                      type: string
                      enum:
                      - EQUALS
                      - NOT_EQUALS
                      - GREATER_THAN
                      - GREATER_THAN_OR_EQUAL_TO
                      - LESS_THAN
                      - LESS_THAN_OR_EQUAL_TO
                      - CONTAINS
                      - STARTS_WITH
                      - IS_SET
                      - IS_NOT_SET
                      description: Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value.
                    value:
                      anyOf:
                      - type: string
                      - type: number
                      - type: boolean
                      description: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET.
                  required:
                  - type
                maxItems: 20
                description: Filters for this measure only, on top of the query's filters.
              isBaseline:
                type: boolean
                description: 'Mark one measure as the baseline: every series also reports its value as a percentage of it.'
              color:
                type: string
                enum:
                - GREEN
                - RED
                - ORANGE
                - PURPLE
                - GREY
                - BLUE
                - PEACH
                - TEAL
                - INDIGO
                - AMBER
                - ROSE
                - CYAN
                description: Chart color on a dashboard.
          minItems: 1
          maxItems: 10
          description: 'What to aggregate: 1 to 10 measures.'
        filters:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - METRIC_PROPERTY
                - CALL_PROPERTY
                - AGENT_PROPERTY
                - CALL_ID
                - MODALITY
                - DATASET
                - METRIC_VALUE
                description: What the filter narrows on. GET /v1/analytics/schema lists each type.
              property:
                type: string
                description: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID.
              operator:
                type: string
                enum:
                - EQUALS
                - NOT_EQUALS
                - GREATER_THAN
                - GREATER_THAN_OR_EQUAL_TO
                - LESS_THAN
                - LESS_THAN_OR_EQUAL_TO
                - CONTAINS
                - STARTS_WITH
                - IS_SET
                - IS_NOT_SET
                description: Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value.
              value:
                anyOf:
                - type: string
                - type: number
                - type: boolean
                description: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET.
            required:
            - type
          maxItems: 20
          description: Applied to every measure, on top of each measure's own filters.
        interval:
          type: string
          enum:
          - HOUR
          - DAY
          - WEEK
          - MONTH
          description: Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets.
        comparisonMode:
          type: string
          enum:
          - NONE
          - PREVIOUS_PERIOD
          description: PREVIOUS_PERIOD adds the preceding window of the same length to every series.
        comparisonGroups:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 100
                description: The series label; unique within the query.
              filters:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                      - METRIC_PROPERTY
                      - CALL_PROPERTY
                      - AGENT_PROPERTY
                      - CALL_ID
                      - MODALITY
                      - DATASET
                      - METRIC_VALUE
                      description: What the filter narrows on. GET /v1/analytics/schema lists each type.
                    property:
                      type: string
                      description: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID.
                    operator:
                      type: string
                      enum:
                      - EQUALS
                      - NOT_EQUALS
                      - GREATER_THAN
                      - GREATER_THAN_OR_EQUAL_TO
                      - LESS_THAN
                      - LESS_THAN_OR_EQUAL_TO
                      - CONTAINS
                      - STARTS_WITH
                      - IS_SET
                      - IS_NOT_SET
                      description: Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value.
                    value:
                      anyOf:
                      - type: string
                      - type: number
                      - type: boolean
                      description: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET.
                  required:
                  - type
                minItems: 1
                maxItems: 20
              color:
                type: string
                enum:
                - GREEN
                - RED
                - ORANGE
                - PURPLE
                - GREY
                - BLUE
                - PEACH
                - TEAL
                - INDIGO
                - AMBER
                - ROSE
                - CYAN
            required:
            - name
            - filters
          minItems: 2
          maxItems: 5
          description: Run every measure once per named filter set, e.g. one group per agent.
        timeRange:
          oneOf:
          - type: object
            properties:
              type:
                type: string
                const: LAST
              value:
                type: integer
                minimum: 1
                maximum: 1000
              unit:
                type: string
                enum:
                - DAYS
                - WEEKS
                - MONTHS
            required:
            - type
            - value
            - unit
          - type: object
            properties:
              type:
                type: string
                const: CALENDAR_ALIGNED
              period:
                type: string
                enum:
                - TODAY
                - YESTERDAY
                - THIS_WEEK
                - LAST_WEEK
                - THIS_MONTH
                - LAST_MONTH
                - THIS_YEAR
                - LAST_YEAR
            required:
            - type
            - period
          - type: object
            properties:
              type:
                type: string
                const: FIXED
              from:
                type: string
                format: date-time
              to:
                type: string
                format: date-time
            required:
            - type
            - from
            - to
          - type: object
            properties:
              type:
                type: string
                const: SINCE
              from:
                type: string
                format: date-time
            required:
            - type
            - from
          description: Defaults to the last 30 days.
        timezone:
          type: string
          minLength: 1
          description: IANA zone that buckets and calendar periods align to, e.g. America/New_York. Defaults to UTC.
        includeBuckets:
          type: boolean
          description: Set false to return only the window totals.
      required:
      - measures
      description: 'An aggregate query: one or more measures over a time window, optionally filtered, broken down and compared. GET /v1/analytics/schema lists the metrics, filters and breakdowns available.'
      example:
        measures:
        - metric: sentiment_score
          aggregation: AVG
        - type: CONVERSATION
          aggregation: COUNT
        timeRange:
          type: LAST
          value: 7
          unit: DAYS
        interval: DAY
        timezone: Europe/London
        filters:
        - type: MODALITY
          value: call
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
          - validation
          - authentication
          - forbidden
          - not_found
          - conflict
          - payment_required
          - rate_limit
          - internal
          description: The error type category
          examples:
          - validation
          - authentication
        code:
          type: string
          description: Machine-readable error code identifier
          examples:
          - invalid_parameter
          - missing_required_field
          - unauthorized
        message:
          type: string
          description: Human-readable error message
          examples:
          - The request was invalid
          - Authentication required
        param:
          type: string
          description: The parameter that caused the error (if applicable)
          examples:
          - email
          - user_id
        details:
          description: Additional error context information
      required:
      - type
      - code
      - message
    AnalyticsResult:
      type: object
      properties:
        from:
          type: string
        to:
          type: string
        interval:
          type: string
          enum:
          - HOUR
          - DAY
          - WEEK
          - MONTH
        timezone:
          type: string
        series:
          type: array
          items:
            type: object
            properties:
              measureIndex:
                type: integer
              type:
                type: string
                enum:
                - METRIC
                - CONVERSATION
                - UPTIME
              metric:
                type:
                - string
                - 'null'
              aggregation:
                type: string
                enum:
                - COUNT
                - AVG
                - MIN
                - MAX
                - SUM
                - MEDIAN
                - PERCENTILE
                - PASS_RATE
              breakdownValue:
                type:
                - string
                - 'null'
              comparisonGroup:
                type:
                - string
                - 'null'
              value:
                type: number
              sampleSize:
                type:
                - number
                - 'null'
              comparisonValue:
                type:
                - number
                - 'null'
              percentageOfBaseline:
                type:
                - number
                - 'null'
              buckets:
                type: array
                items:
                  type: object
                  properties:
                    date:
                      type: string
                    value:
                      type: number
                    passed:
                      type: number
                    sampleSize:
                      type: number
                    comparisonDate:
                      type: string
                    comparisonValue:
                      type: number
                    percentageOfBaseline:
                      type: number
                  required:
                  - date
                  - value
            required:
            - measureIndex
            - type
            - metric
            - aggregation
            - breakdownValue
            - comparisonGroup
            - value
            - sampleSize
            - comparisonValue
            - percentageOfBaseline
            - buckets
        omittedSeries:
          type: integer
      required:
      - from
      - to
      - interval
      - timezone
      - series
      - omittedSeries
      description: One series per measure (or per breakdown value / comparison group). `value` is the aggregate over the whole window; `buckets` hold the per-interval values.
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT