KaiCalls Analytics API

openapi: 3.2.0
info:
  title: KaiCalls Public Analytics API
  version: '2026-06-05'
  description: Machine-readable surface for KaiCalls external developers and client agents.
servers:
- url: https://www.kaicalls.com/api
security:
- bearerAuth: []
tags:
- name: Analytics
paths:
  /v1/analytics/dashboard:
    get:
      summary: Return aggregated dashboard analytics for a workspace
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Dashboard analytics
      x-required-scopes: calls:read
      tags:
      - Analytics
      operationId: getV1AnalyticsDashboard
      x-operation-id-source: derived
  /v1/analytics/bookings:
    get:
      summary: Observe local mirrored appointments scheduled to start in a UTC range
      description: Requires appointments:read and accessible businesses. Counts current mirror statuses confirmed/completed/no_show; cancelled and unknown statuses are separate diagnostics. Includes ai_agent (voice/chat), manual, widget, api, website and unknown sources. Mirror/provider coverage is unknown; pagination is not a snapshot. This is not bookings-created, conversion or provider-total analytics.
      parameters:
      - name: range
        in: query
        required: false
        schema:
          type: string
          enum:
          - 7d
          - 30d
          - custom
          default: 7d
        description: Rolling UTC 7/30 days or an explicit custom range, compared with the adjacent equal-duration prior range.
      - name: start
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: 'Required only for custom: canonical YYYY-MM-DDTHH:mm:ss.sssZ, inclusive. Custom duration is at most 90 days; the prior range must start no earlier than 365 days before the request.'
      - name: end
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: 'Required only for custom: canonical YYYY-MM-DDTHH:mm:ss.sssZ, exclusive, at most 365 days after the request. Future scheduled appointments are allowed.'
      - name: business_id
        in: query
        required: false
        schema:
          type: string
        description: Optionally narrow to one business already accessible to the supplied API authorization.
      responses:
        '200':
          description: Observed scheduled mirror counts and six source buckets for current/prior ranges. Unknown statuses make counts lower bounds and suppress comparison; zero prior produces null percentage change. Mirror coverage remains unknown.
        '400':
          description: Invalid/duplicate/unknown query, invalid range or scope exceeding 100 businesses; select a shorter range or one business where applicable.
        '401':
          description: Existing API authorization refusal.
        '403':
          description: Missing appointments:read scope or inaccessible business.
        '503':
          description: 'Unavailable/incomplete observation: failed/missing data, unstable or invalid pages, or limits of 5000 rows / 20 pages. Counts and comparisons are null, never fabricated zeros.'
      x-required-scopes: appointments:read
      tags:
      - Analytics
      operationId: getV1AnalyticsBookings
      x-operation-id-source: derived
  /v1/analytics/calls:
    get:
      summary: Return call-volume analytics grouped over time for a workspace
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
      - name: group_by
        in: query
        required: false
        schema:
          type: string
      - name: agent_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Call analytics
      x-required-scopes: calls:read
      tags:
      - Analytics
      operationId: getV1AnalyticsCalls
      x-operation-id-source: derived
  /v1/analytics/agents:
    get:
      summary: Return per-agent performance analytics for a workspace
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
      - name: agent_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Agent analytics
      x-required-scopes: calls:read
      tags:
      - Analytics
      operationId: getV1AnalyticsAgents
      x-operation-id-source: derived
  /v1/analytics/businesses:
    get:
      summary: Return per-business analytics across the calling key user accessible…
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Business analytics, including signup_attribution
      x-required-scopes: calls:read
      tags:
      - Analytics
      operationId: getV1AnalyticsBusinesses
      x-operation-id-source: derived
  /v1/analytics/funnel:
    get:
      summary: Return lead/call funnel analytics for a workspace
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
      - name: source
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Funnel analytics
      x-required-scopes: leads:read
      tags:
      - Analytics
      operationId: getV1AnalyticsFunnel
      x-operation-id-source: derived
  /v1/analytics/weekly:
    get:
      summary: Return the weekly analytics rollup for a workspace
      responses:
        '200':
          description: Weekly analytics
      x-required-scopes: calls:read
      tags:
      - Analytics
      operationId: getV1AnalyticsWeekly
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'KaiCalls API key. Per-operation scope requirements are published on each operation as `x-required-scopes` — a scope string, or a nested `{ allOf: [...] }` / `{ anyOf: [...] }` expression. An operation with no `x-required-scopes` requires a valid key but no particular scope.'
      x-scopes:
      - workspaces:read
      - workspaces:write
      - numbers:read
      - numbers:write
      - agents:read
      - agents:write
      - communication-runs:read
      - communication-runs:write
      - calls:read
      - calls:write
      - sms:read
      - sms:write
      - webhooks:read
      - webhooks:write
      - events:read
      - events:replay
      - lifecycle:write
      - leads:read
      - leads:write
      - emails:read
      - emails:write
      - sdr:read
      - sdr:write
      - evals:read
      - evals:write
      - appointments:read
      - appointments:write
      - knowledge:read
      - knowledge:write
      - products:read
      - products:write
      - integrations:write
      - approvals:write
      - concierge:write
      - billing:read
      - billing:write
      - call_evidence:read
      - call_evidence:write
      - support:write
    sessionAuth:
      type: apiKey
      in: cookie
      name: sb-access-token
      description: Authenticated dashboard session cookie. Used by first-party flows that mint or manage API keys.