canarics-com Calls API

openapi: 3.2.0
info:
  title: Canarics API for AI agents Calls API
  version: 1.0.0
  description: 'API that lets a client''s own AI assistant (Claude, ChatGPT, or any tool with HTTP access) check the client''s Canarics account: minute usage vs plan, AI voice agents, call history and daily call statistics.


    No Canarics account yet? An AI assistant can set the whole thing up: POST /api/v1/signup (no auth) starts a signup and returns a claim URL for the person responsible (they sign in, verify their phone, accept terms); GET /api/v1/signup/status then hands the assistant a one-time API key for the new team, and POST /api/v1/upgrade/checkout returns the hosted payment link the person opens to pay. The human stays in the loop exactly where it matters (identity, phone, terms, payment); everything else is machine-driven.


    Dashboard deep links (hand to the human, manager login required): https://canarics.com/manager.html#/team for API keys and team members; each agent''s manageUrl (conversations) and settingsUrl (prompt, voice, tools, Pipedrive token, Telegram, calendar), both returned by GET /api/v1/agents. These are the only valid dashboard links, never construct others.


    Getting a key: a team manager creates an API key in the Canarics dashboard (Team tab), or the signup flow above delivers one. Keys look like `cnr_`, are scoped to one team, and are read-only. Keep them secret; a manager can revoke a key at any time.


    All endpoints return JSON. Errors use `{ "error": "snake_case_code", "hint": "human/agent-readable explanation" }`. Rate limits: 120 requests per minute and 5000 requests per UTC day per key (HTTP 429 when exceeded). Do not poll for new calls, register the team webhook and react to call.analyzed / call.missed events instead.


    MCP: the same data is exposed as a remote MCP server (Streamable HTTP, stateless) at `POST https://canarics.com/mcp`, authenticated with the same Bearer key. Listed in the official MCP registry as com.canarics/canarics. Tools: get_usage, list_agents, list_calls, list_conversations, get_daily_call_stats, get_contact, get_upgrade_options, create_upgrade_checkout (plus request_callback on callbacks-scoped keys); with no key at all, the signup tools start_signup and check_signup_status. Claude Code: `claude mcp add --transport http canarics https://canarics.com/mcp --header "Authorization: Bearer cnr_..."`.


    Outbound webhook (Canarics -> your API): a manager can register an HTTPS URL in the dashboard; Canarics then POSTs events. `call.analyzed` fires after every analyzed call (human and AI-agent calls) with fields: event, teamId, source (human_call | ai_agent_call), callId, userId or agentId, direction, number, durationSeconds, summary, score, sentiment, keyFacts, nextSteps, dealInfo, talkRatio, listenRatio, clientName, timestamp. `call.missed` fires the moment a customer''s inbound call is logged as missed, with: event, teamId, source, userId, direction, number (as delivered by the carrier, may lack the + prefix; contacts and callbacks endpoints accept either form), timestamp, react to it by checking history (GET /api/v1/contacts/{number}) and, with a callbacks-scoped key, scheduling an AI callback (POST /api/v1/callbacks). Each delivery carries `X-Canarics-Event`, `X-Canarics-Timestamp` (unix seconds) and `X-Canarics-Signature: sha256=HMAC_SHA256(secret, "{timestamp}.{rawBody}")` computed with the team''s signing secret (shown in the dashboard). Respond 2xx within 10s; failed deliveries retry twice (2s/4s backoff) and the webhook auto-disables after 100 consecutive failures.


    Scopes: keys are read-only by default. On the Canarics outbound plan, a manager can create a key with the `callbacks` scope, which additionally allows POST /api/v1/callbacks (and the request_callback MCP tool), scheduling an AI voice-agent callback to a number the team already has call history with. Teams without the outbound plan get 403 outbound_plan_required. Never a cold-calling API: unknown numbers are rejected.'
  contact:
    email: sales@canarics.com
    url: https://canarics.com
servers:
- url: https://salestick-backend-647994203646.europe-central2.run.app
  description: Production (EU, europe-central2)
security:
- bearerKey: []
- apiKeyHeader: []
tags:
- name: Calls
paths:
  /api/v1/calls:
    get:
      summary: Call log summaries (newest first, paginated)
      parameters:
      - name: from
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: ISO 8601 start, e.g. 2026-09-01
      - name: to
        in: query
        schema:
          type: string
          format: date-time
        description: ISO 8601 end; defaults to now
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 200
          default: 100
      - name: cursor
        in: query
        schema:
          type: string
        description: Pass the `cursor` value from the previous page
      - name: direction
        in: query
        schema:
          type: string
          enum:
          - inbound
          - outbound
        description: Filter applied to the returned page
      - name: missed
        in: query
        schema:
          type: string
          enum:
          - 'true'
        description: Only missed calls (filter applied to the returned page)
      responses:
        '200':
          description: Page of calls
          content:
            application/json:
              schema:
                type: object
                properties:
                  calls:
                    type: array
                    items:
                      $ref: '#/components/schemas/Call'
                  cursor:
                    type:
                    - string
                    - 'null'
                  hasMore:
                    type: boolean
        '400':
          description: Missing/invalid from
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Calls
      operationId: getApiV1Calls
      x-operation-id-source: derived
  /api/v1/calls/daily-stats:
    get:
      summary: Per-day call statistics (max 90 days)
      parameters:
      - name: from
        in: query
        schema:
          type: string
          format: date
      - name: to
        in: query
        schema:
          type: string
          format: date
      - name: days
        in: query
        schema:
          type: integer
          maximum: 90
          default: 7
        description: 'Used when from is omitted: last N days'
      - name: tz
        in: query
        schema:
          type: string
          default: Europe/Riga
        description: IANA timezone for day boundaries
      responses:
        '200':
          description: Daily rollups
          content:
            application/json:
              schema:
                type: object
                properties:
                  days:
                    type: array
                    items:
                      type: string
                  stats:
                    type: array
                    items:
                      $ref: '#/components/schemas/DailyStat'
      tags:
      - Calls
      operationId: getApiV1CallsDailyStats
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        hint:
          type: string
    Call:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
          description: Counterparty phone number, E.164
        direction:
          type: string
          enum:
          - inbound
          - outbound
        status:
          type: string
        createdAt:
          type: string
          format: date-time
        summary:
          type: string
          description: AI-written call summary
        score:
          type: number
          description: AI quality score 1-10
        sentiment:
          type: string
        isMissed:
          type: boolean
        recoveredAt:
          type: string
          format: date-time
          description: When a missed call was called back
        manualName:
          type: string
        userId:
          type: string
          description: Id of the team member (or AI agent) on the call
    DailyStat:
      type: object
      properties:
        date:
          type: string
          example: '2026-09-01'
        total:
          type: number
        inbound:
          type: number
        outbound:
          type: number
        missed:
          type: number
        missedInbound:
          type: number
        recovered:
          type: number
        scored:
          type: number
          description: Calls that received an AI score
        scoreSum:
          type: number
          description: Sum of scores; average = scoreSum / scored
        durationSum:
          type: number
          description: Total call seconds that day
  securitySchemes:
    bearerKey:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer cnr_...'
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key