The Ultimate Developer API Guide

All API endpoints require a Chirps API Key in the Authorization header. You can generate an API key from the API Manager in the Developer section of your dashboard.

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

Example Request:

curl -X GET https://chirps.cc/api/billing/usage \
  -H "Authorization: Bearer <YOUR_CHIRPS_API_KEY>" \
  -H "Content-Type: application/json"

Standard Error Handling

List Assistants

Fetches a list of all assistants associated with the API key's workspace.

Create an Assistant

POST /api/assistants

Creates a new assistant with all base configurations.

{

  "businessName": "Acme Corp",
  "businessUrl": "https://acme.com",
  "knowledgeBaseType": "both",
  "knowledgeBaseUrl": "https://acme.com/help",
  "knowledgeBaseText": "Raw text content of a document...",
  "knowledgeBaseFileName": "company_handbook.pdf",
  "language": "en",
  "isMultiLanguage": false,
  "tonePersonality": "professional",
  "isCustomPersonality": false,
  "supportEmail": "[email protected]",
  "maxPages": 5,
  "maxDepth": 2,
  "welcomeMessageDelay": 2
}

Delete Assistant

DELETE /api/assistants/:id

Permanently deletes the assistant and cascadingly deletes all its knowledge nodes and history. No payload required.

GET /api/analytics/overview?assistantId=uuid&range=30

Fetch usage statistics, total messages, leads captured, and general engagement metrics for the specified assistant. The range parameter is optional (number of days, min 7, max 365, default 30).

Expected Response

{

  "totalConversations": 1245,
  "totalMessages": 8420,
  "totalLeads": 156,
  "totalBookings": 42,
  "satisfactionRate": 94,
  "avgMessagesPerSession": 6.7,
  "avgSessionsPerDay": 41.5,
  "liveNow": 3,
  "onlineNow": 12,
  "dailySeries": [
    {
      "date": "2026-07-15",
      "conversations": 45,
      "messages": 310,
      "leads": 5,
      "bookings": 2
    }
  ],
  "agentStats": [
    {
      "name": "Jane Doe",
      "messagesSent": 120,
      "csat": 98
    }
  ]
}

Managing Knowledge Nodes

GET /api/assistants/:id/nodes - List all knowledge nodes for this assistant.

POST /api/assistants/:id/nodes - Manually inject a new knowledge block.

{

  "title": "Return Policy",
  "refined_content": "We offer a 30-day return policy for all unused items...",
  "type": "text",
  "metadata": {}
}

PATCH /api/assistants/:id/nodes/:nodeId - Modify an existing node's content or toggle its active state.

{

  "title": "Updated Return Policy",
  "refined_content": "We offer a 60-day return policy now...",
  "is_active": true
}

DELETE /api/assistants/:id/nodes/:nodeId - Delete a knowledge block entirely.

POST /api/assistants/:id/nodes/:nodeId/re-crawl - Force the scraper to re-crawl the URL associated with this node and update its content. Payload: {}.

AI Training

POST /api/assistants/:id/train - Compile all is_active knowledge nodes and use an AI orchestrator to dynamically synthesize a new Master System Prompt. Payload: {}.

Update Widget Appearance

PATCH /api/assistants/:id/widget-config

{

  "primaryColor": "#000000",
  "position": "bottom-right",
  "language": "en",
  "welcomeMessage": "Hi! How can I help you today?",
  "title": "Acme Support",
  "theme": "light",
  "fontFamily": "default",
  "bubbleStyle": "circle",
  "bubbleText": "Chat with us",
  "headerSubtitle": "We typically reply instantly",
  "inputPlaceholder": "Type your message...",
  "privacyPolicyUrl": "https://acme.com/privacy",
  "voiceEnabled": true,
  "voiceName": "Fenrir",
  "welcomeMessageDelay": 2,
  "fileUploadEnabled": true,
  "dictationEnabled": true,
  "copilotEnabled": true,
  "welcomeSuggestions": ["Pricing plans", "Contact sales"],
  "pageVisibility": {
    "mode": "all",
    "paths": []
  }
}

Available Voice Names

• Female: Zephyr, Aoede, Kore, Leda, Callirrhoe, Despina, Erinome, Laomedeia, Achernar, Pulcherrima, Gacrux, Algenib, Sulafat
• Male: Puck, Charon, Fenrir, Orus, Enceladus, Iapetus, Umbriel, Algieba, Autonoe, Rasalgethi, Alnilam

Custom Logo

POST /api/assistants/:id/widget-logo

Format: multipart/form-data with file field.

Option A: Web Embed (Frontend)

The easiest way to integrate the assistant into a standard website (WordPress, Shopify, React, etc.). The embed code is purely deterministic. You do not need an endpoint to fetch it. Just drop this in the <head> of your site:

<script src="https://chirps.cc/widget.js" data-assistant-id="YOUR_ASSISTANT_ID_HERE"></script>

Option B: Headless Integrations (Backend / CRMs / Bots)

If you are building a custom client (like a Discord bot, a Telegram integration, or a native iOS app), you will NOT use the Web Embed. Instead, you will interact directly with the /api/chat endpoint.

POST /api/chat or /api/chat?stream=true

Note: This endpoint is public and does *not* require the Authorization: Bearer API Key header. Authentication is handled implicitly via the assistantId.

{

  "assistantId": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "unique-session-id-for-user",
  "conversationId": "optional-uuid",
  "message": "Hello, I need help with my billing."
}

*(Also supports multipart/form-data with a file field for attachments if fileUploadEnabled is true).*

Mode 1: Standard JSON Response (Default)

By sending a POST request to /api/chat (without the stream parameter), you wait for the full AI response and receive a standard JSON object.

{

  "message": "Here is the information you requested...",
  "conversationId": "uuid-of-conversation",
  "messageId": "uuid-of-message"
}

*(If is_active_agent: true is returned, a human has taken over the chat, and message will be null.)*

Mode 2: Server-Sent Events Streaming (?stream=true)

By appending ?stream=true to the URL, you receive a real-time Server-Sent Events (SSE) stream. Your code should listen for these specific event types:

• `event: token`: Contains {"text": "chunk"}. Fired for each chunk of the AI's response text.
• `event: status`: Contains {"text": "Searching knowledge base..."}. Represents backend tool execution states.
• `event: done`: Contains {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}. Fired when generation is completely finished.
• `event: error`: Contains {"error": "Error message"}. Fired if rate limits or errors occur.

Live Takeover Endpoints

GET /api/chat/sessions

Retrieve historical sessions.

POST /api/chat/toggle-agent

Pause AI for human takeover. Payload: { "sessionId": "..." }

POST /api/chat/agent-message

Send human message. Payload: { "sessionId": "...", "message": "..." }

Update Core Configuration

Modify the core settings, persona, and scraping bounds of the assistant.

{

  "business_name": "Acme Corp",
  "business_url": "acme.com",
  "business_description": "We sell anvils.",
  "system_prompt": "You are a helpful assistant.",
  "language": "en",
  "tone_personality": "Friendly",
  "support_email": "[email protected]",
  "additional_instructions": "Never mention the Roadrunner.",
  "is_multi_language": true,
  "is_dev_mode": false,
  "is_active": true,
  "max_pages": 15,
  "max_depth": 2,
  "widget_config_merge": {
    "rateLimitEnabled": true
  }
}

*Note: All fields are optional. Only send the fields you want to update.*

Delete Assistant

DELETE /api/assistants/:id

Permanently deletes the assistant and cascades deletion to all knowledge nodes, conversations, and messages. If the assistant was never fully set up, this refunds the monthly creation quota.

POST /api/phone-numbers/:id/assign - Provision a number. Payload: {}

POST /api/assistants/:id/outbound - Trigger outbound call. Payload: { "to": "+123...", "message": "..." }

GET /api/leads?id=leadId - Fetch details of a single lead, including the full conversation transcript.

GET /api/bookings?id=bookingId - Fetch details of a single booking, including the conversation transcript.

POST /api/bookings/cancel - Cancel an active booking. Payload: { "bookingId": "uuid" }

POST /api/bookings/reschedule - Adjust a booking. Payload: { "bookingId": "uuid", "newTime": "ISO-8601" }

Retrieve the workspace's billing cycle usage, subscription plan limits, and total assistant count. Note: When using an API Key, the request is automatically scoped to the API Key's workspace; you do not need to provide a teamId.

Response (`200 OK`):

{

  "planName": "Pro",
  "periodStr": "2023-10-01",
  "assistantCount": 3,
  "usage": {
    "message_count": 1450,
    "harvest_count": 12,
    "recrawl_count": 5,
    "train_count": 2,
    "assistants_created_count": 1,
    "voice_minutes_used": 0,
    "sms_count": 0,
    "email_count": 0,
    "whatsapp_count": 0
  },
  "limits": {
    "messages": 5000,
    "assistants": 5,
    "training": 50,
    "recrawls": 20
  },
  "workspaceOwnerId": "uuid"
}