canarics-com Campaigns API

openapi: 3.2.0
info:
  title: Canarics API for AI agents Campaigns 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: Campaigns
paths:
  /api/v1/campaigns:
    get:
      summary: List outbound campaigns with live state (campaigns scope required)
      description: 'The team''s outbound calling campaign templates: enabled or draft, calls made today vs the daily limit, leads remaining, last feed error. Call outcomes come from GET /api/v1/conversations with direction=outbound.'
      responses:
        '200':
          description: Campaign list
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaigns:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        enabled:
                          type: boolean
                        draft:
                          type: boolean
                        createdVia:
                          type: string
                          enum:
                          - ai_assistant
                          - dashboard
                        agentId:
                          type: string
                        poolId:
                          type:
                          - string
                          - 'null'
                        callsPerDay:
                          type:
                          - integer
                          - 'null'
                        calledToday:
                          type: integer
                        poolRemaining:
                          type:
                          - integer
                          - 'null'
                        lastFedAt:
                          type:
                          - string
                          - 'null'
                        lastError:
                          type:
                          - string
                          - 'null'
                        createdAt:
                          type:
                          - string
                          - 'null'
                  manageUrl:
                    type: string
                  note:
                    type: string
        '403':
          description: Key lacks the campaigns scope
      tags:
      - Campaigns
      operationId: getApiV1Campaigns
      x-operation-id-source: derived
    post:
      summary: Draft an outbound calling campaign (campaigns scope required).
      description: 'Creates a DISABLED campaign draft that a human team manager must review and launch in the Canarics dashboard (Outbound tab); no calls are placed by this endpoint. The brief becomes the calling agent''s only context, so ground it in what the company actually wants from these calls. Audience is either an existing lead pool (poolId) or up to 200 numbers the company already has a lawful basis to call. Once launched by the manager, calls run through the normal outbound loop: daily limit, local calling window, retries, spacing.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - brief
              properties:
                name:
                  type: string
                  minLength: 3
                  maxLength: 80
                  description: Short campaign name the manager will recognize in the dashboard
                brief:
                  type: string
                  minLength: 20
                  maxLength: 800
                  description: Why these people are being called and what a good call achieves, in plain words grounded in the company's own request
                agentId:
                  type: string
                  description: Which voice agent places the calls, needed only when the team has several
                poolId:
                  type: string
                  description: Existing lead pool to call from. Pass either this or numbers, not both
                numbers:
                  type: array
                  maxItems: 200
                  description: Ad-hoc audience. Only numbers the company may lawfully call
                  items:
                    type: object
                    required:
                    - number
                    properties:
                      number:
                        type: string
                        description: E.164
                      name:
                        type: string
                      note:
                        type: string
                        description: Short per-person context, e.g. what they asked about
                language:
                  type: string
                  description: Opening language, defaults to the agent's language
                timezone:
                  type: string
                  description: IANA timezone for the calling window, default Europe/Riga
                callsPerDay:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: Daily call limit once launched, default 20
                allowedHours:
                  type: object
                  properties:
                    startHour:
                      type: integer
                    endHour:
                      type: integer
                  description: Local calling window, default 9-20
      responses:
        '201':
          description: Draft created, waiting for a manager to launch
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaignId:
                    type: string
                  status:
                    type: string
                    enum:
                    - draft
                  poolId:
                    type: string
                  audience:
                    type: object
                    properties:
                      added:
                        type: integer
                      poolRemaining:
                        type: integer
                      rejected:
                        type: array
                        items:
                          type: object
                  callsPerDay:
                    type: integer
                  reviewUrl:
                    type: string
                  note:
                    type: string
        '400':
          description: Missing name/brief, no valid audience, or invalid settings
        '403':
          description: Key lacks the campaigns scope, team not on the outbound plan, or pool dial policy blocks calling
        '404':
          description: Pool not found on this team
        '429':
          description: Daily draft limit reached (10 per team)
      tags:
      - Campaigns
      operationId: postApiV1Campaigns
      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