canarics-com Canarics API For AI Agents API

openapi: 3.2.0
info:
  title: Canarics API For AI Agents 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: Canarics API For AI Agents
paths:
  /api/v1:
    get:
      summary: Discovery, endpoint list and auth instructions
      security: []
      responses:
        '200':
          description: Endpoint directory
      tags:
      - Canarics API For AI Agents
      operationId: getApiV1
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerKey:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer cnr_...'
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key