canarics-com Tools API

openapi: 3.2.0
info:
  title: Canarics API for AI agents Tools 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: Tools
paths:
  /api/v1/tools:
    get:
      summary: List team-defined HTTP tools on the voice agents (tools scope required)
      description: Custom mid-call tools created via POST /api/v1/tools or the MCP create_agent_tool. Header values are masked. Built-in Canarics tools are not listed.
      responses:
        '200':
          description: Tools per agent
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      type: object
                      properties:
                        agentId:
                          type: string
                        agentName:
                          type:
                          - string
                          - 'null'
                        tools:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                              description:
                                type: string
                              params:
                                type: array
                                items:
                                  type: object
                              method:
                                type: string
                              url:
                                type: string
                              headers:
                                type: object
                                description: Values masked.
                              responseFields:
                                type: array
                                items:
                                  type: string
                              timeoutMs:
                                type: integer
                              enabled:
                                type: boolean
                              createdAt:
                                type:
                                - string
                                - 'null'
                  note:
                    type: string
        '403':
          description: Key lacks the tools scope
      tags:
      - Tools
      operationId: getApiV1Tools
      x-operation-id-source: derived
    post:
      summary: Create a custom mid-call tool on a voice agent (tools scope required)
      description: Wires the company's OWN HTTPS API into the voice agent as a mid-call tool (e.g. order lookup, booking check). The URL host is pinned at creation; caller-supplied values only fill {param} placeholders in path/query/body. Always verify with POST /api/v1/tools/test afterwards. Grounding rules (param values must come from the caller's own words) are enforced automatically.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - description
              - method
              - url
              properties:
                agentId:
                  type: string
                  description: Which voice agent gets the tool - required only when the team has several (ids from GET /api/v1/agents).
                name:
                  type: string
                  description: snake_case tool name, 3-41 chars, e.g. check_order_status.
                description:
                  type: string
                  description: 'For the voice AI: when to call this tool and what it returns.'
                params:
                  type: array
                  description: Values the voice AI extracts from the caller's words.
                  items:
                    type: object
                    required:
                    - name
                    - type
                    - description
                    properties:
                      name:
                        type: string
                      type:
                        type: string
                        enum:
                        - string
                        - number
                        - boolean
                      description:
                        type: string
                      required:
                        type: boolean
                        default: true
                method:
                  type: string
                  enum:
                  - GET
                  - POST
                url:
                  type: string
                  description: HTTPS endpoint; {param} placeholders allowed in path/query, never in the host. Host must be publicly reachable (no private/internal addresses).
                headers:
                  type: object
                  additionalProperties:
                    type: string
                  description: Static headers, e.g. an Authorization header. Stored server-side, masked in listings.
                body:
                  type: object
                  description: 'POST only: JSON body template; string values may contain {param} placeholders.'
                responseFields:
                  type: array
                  items:
                    type: string
                  description: Allowlist of response fields (dot paths) the voice AI is shown. Strongly recommended.
                timeoutMs:
                  type: integer
                  minimum: 1000
                  maximum: 10000
                  default: 6000
      responses:
        '201':
          description: Tool created (live on new calls immediately)
        '400':
          description: Invalid tool spec, unresolvable/private host, agentId needed, or tool limit reached
        '409':
          description: A tool with that name already exists on the agent
        '403':
          description: Key lacks the tools scope
      tags:
      - Tools
      operationId: postApiV1Tools
      x-operation-id-source: derived
  /api/v1/tools/test:
    post:
      summary: Dry-run a team-defined tool through the exact live-call executor (tools scope…
      description: Runs the tool with sample args and returns the interpolated request URL plus the response the voice AI would see. Do this after every create and confirm the data is correct and safe to speak aloud.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                agentId:
                  type: string
                args:
                  type: object
                  description: 'Sample param values, e.g. {"order_number": "LV-10293"}.'
      responses:
        '200':
          description: Executor result with debug info (requestUrl, response data or failure reason)
        '404':
          description: No tool with that name
        '403':
          description: Key lacks the tools scope
      tags:
      - Tools
      operationId: postApiV1ToolsTest
      x-operation-id-source: derived
  /api/v1/tools/{name}:
    delete:
      summary: Remove a team-defined tool (tools scope required)
      description: 'Takes effect on new calls immediately. To replace a misconfigured tool: delete, then create again, then test.'
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      - name: agentId
        in: query
        required: false
        schema:
          type: string
        description: Needed only when several agents have a tool with the same name.
      responses:
        '200':
          description: Deleted
        '404':
          description: No tool with that name
        '403':
          description: Key lacks the tools scope
      tags:
      - Tools
      operationId: deleteApiV1ToolsByName
      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