Der ultimative Entwickler-API-Leitfaden

Alle API-Endpunkte erfordern einen Chirps-API-Schlüssel im „Authorization“-Header. Sie können einen API-Schlüssel vom API Manager im Entwicklerbereich Ihres Dashboards generieren.

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

Beispielanfrage:

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

Standardfehlerbehandlung

Berechtigungen und geringste Rechte

Jeder Schlüssel ist auf seine ausgewählten Berechtigungen beschränkt. Verwenden Sie möglichst schreibgeschützte und für jede Integration getrennte Schlüssel. Eine Schreibberechtigung enthält nicht automatisch die entsprechende Leseberechtigung.

assistants:read
assistants:write
analytics:read
artifacts:read
artifacts:write
billing:read
bookings:read
bookings:write
chat:write
connectors:read
connectors:write
conversations:read
conversations:write
knowledge:read
knowledge:write
leads:read
leads:write
telephony:read
telephony:write
widget:write

API-key rate limit

Each developer key is limited to 300 requests per rolling minute by default. The limit is atomic across all application instances and can be changed by the platform with API_KEY_RATE_LIMIT_PER_MINUTE. A rejected request returns 429; retry only after the window resets.

Assistenten auflisten

Ruft eine Liste aller Assistenten ab, die dem Arbeitsbereich des API-Schlüssels zugeordnet sind.

Erstellen Sie einen Assistenten

POST /api/assistants

Erstellt einen neuen Assistenten mit allen Basiskonfigurationen.

{

  "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
}

Assistent löschen

DELETE /api/assistants/:id

Löscht den Assistenten dauerhaft und löscht nach und nach alle seine Wissensknoten und seinen Verlauf. Keine Nutzlast erforderlich.

Creation validation and quota safety

Creation allowance is reserved atomically before insertion, so concurrent requests cannot exceed the monthly quota. Database insertion failures refund that reservation. A created assistant starts inactive in developer mode; call the setup endpoint and wait for its successful terminal event before publishing it.

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

Rufen Sie Nutzungsstatistiken, Gesamtnachrichten, erfasste Leads und allgemeine Engagement-Metriken für den angegebenen Assistenten ab. Der Parameter „Bereich“ ist optional (Anzahl der Tage, min. 7, max. 365, Standard 30).

Erwartete Antwort

{

  "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
    }
  ]
}

Wissensknoten verwalten

GET /api/assistants/:id/nodes – Alle Wissensknoten für diesen Assistenten auflisten.

POST /api/assistants/:id/nodes – Manuelles Einfügen eines neuen Wissensblocks.

{

  "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 – Ändern Sie den Inhalt eines vorhandenen Knotens oder schalten Sie seinen aktiven Status um.

{

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

DELETE /api/assistants/:id/nodes/:nodeId – Einen Wissensblock vollständig löschen.

POST /api/assistants/:id/nodes/:nodeId/re-crawl – Zwingt den Scraper, die mit diesem Knoten verknüpfte URL erneut zu crawlen und ihren Inhalt zu aktualisieren. Nutzlast: „{}“.

KI-Training

„POST“ /api/assistants/:id/train – Kompilieren Sie alle „is_active“-Wissensknoten und verwenden Sie einen KI-Orchestrator, um dynamisch eine neue Master-System-Eingabeaufforderung zu synthetisieren. Nutzlast: „{}“.

Upload, crawl, and index consistency

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

Send only the fields you want to change. The API rejects unknown keys and invalid nested data instead of silently storing configuration the widget cannot use.

{
  "designPreset": "corporate-soft",
  "primaryColor": "#1972F5",
  "theme": "dark",
  "bubbleStyle": "branded-drawer",
  "bubbleText": "Talk to our team",
  "welcomeMessages": [
    {
      "text": "Hello! How can I help?",
      "delay": 1.5
    }
  ],
  "welcomeSuggestions": [
    "View pricing",
    "Book a demo"
  ],
  "pageVisibility": {
    "mode": "exclude",
    "paths": [
      "/checkout/*"
    ]
  },
  "voiceEnabled": true,
  "voiceName": "Aoede",
  "copilotEnabled": true,
  "gdprConsentEnabled": true,
  "privacyPolicyUrl": "https://example.com/privacy"
}

Page visibility matching

Use exact paths such as /pricing, or append /* to include descendants such as /docs/*. include shows only matches; exclude hides matches; all ignores paths. Full URLs are normalized to their pathname by the widget.

Available voice names

Zephyr, Aoede, Kore, Leda, Callirrhoe, Despina, Erinome, Laomedeia, Achernar, Pulcherrima, Gacrux, Algenib, Sulafat, Puck, Charon, Fenrir, Orus, Enceladus, Iapetus, Umbriel, Algieba, Autonoe, Rasalgethi, Alnilam, Schedar, Sadachbia, Achird, Zubenelgenubi, Sadaltager

GET /api/assistants/:id/artifacts · PUT /api/assistants/:id/artifacts · PATCH /api/assistants/:id/artifacts

Artifacts are tool-driven UI. The model calls the enabled tool and Chirps renders it; integrations must send configuration JSON, never {{ARTIFACT: ...}} strings.

{
  "form": {
    "enabled": true,
    "title": "Request a quote",
    "description": "Collect the details needed for a quote.",
    "triggerRules": "When a visitor explicitly asks for a quote.",
    "fields": [
      {
        "key": "name",
        "label": "Full name",
        "type": "text",
        "required": true,
        "placeholder": "Jane Doe"
      },
      {
        "key": "email",
        "label": "Work email",
        "type": "email",
        "required": true
      }
    ],
    "submitLabel": "Request quote"
  },
  "booking": {
    "enabled": true,
    "title": "Book a consultation",
    "description": "Choose an available time.",
    "triggerRules": "When a visitor asks to book a meeting.",
    "services_enabled": false,
    "meetings_enabled": true,
    "requiresScheduling": true,
    "timezone": "Europe/Paris",
    "slotDuration": 30,
    "bufferMinutes": 10,
    "workingHours": {
      "monday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "tuesday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "wednesday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "thursday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "friday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "saturday": {
        "enabled": false,
        "start": "10:00",
        "end": "14:00"
      },
      "sunday": {
        "enabled": false,
        "start": "10:00",
        "end": "14:00"
      }
    },
    "blockedDates": [
      "2026-12-25"
    ],
    "meeting_intake_fields": [
      {
        "key": "email",
        "label": "Email",
        "type": "email",
        "required": true
      }
    ],
    "submitLabel": "Book meeting"
  },
  "card": {
    "enabled": false,
    "ctaLabel": "View details",
    "ctaUrl": "",
    "description": "",
    "triggerRules": ""
  },
  "csat_survey": {
    "enabled": true,
    "title": "How was your experience?",
    "description": "One-click feedback.",
    "triggerRules": "Only after the request is resolved."
  },
  "custom": []
}

Field schema

Booking service schema

Validation limits and scheduling rules

Tool-call prefill behavior

Start with GET /api/marketplace/connectors. Its provider definitions are the source of truth for credential fields, configuration fields, available tools, defaults, and required values; this keeps custom and future providers discoverable without a documentation release.

{
  "provider": "shopify",
  "name": "Shopify",
  "credentials": {}
}

1. Install the workspace connector record with POST /api/assistants/:id/connectors; credentials must be omitted or {}.
2. Read its exact field schema from GET /api/marketplace/connectors and activate it with POST /api/assistants/:id/connectors/:connectorId/activate.
3. Send configValues, optional enabledTools, and optional instructions. Chirps verifies non-custom connectors and discovers the tools before saving the integration.
4. Rotate secrets by calling the activation endpoint again. PUT only renames a named Custom API.
5. Use DELETE /api/assistants/:id/connectors with { connectorId } to disable it for one assistant. Use the nested DELETE .../:connectorId only to permanently remove it from the workspace and every assistant.

Option A: Web-Einbettung (Frontend)

Der einfachste Weg, den Assistenten in eine Standard-Website (WordPress, Shopify, React usw.) zu integrieren. Der Einbettungscode ist rein deterministisch. Sie benötigen keinen Endpunkt, um es abzurufen. Fügen Sie dies einfach in den „<head>“ Ihrer Website ein:

<script>
  window.chirpsConfig = { assistantId: "YOUR_ASSISTANT_ID" };
</script>
<script src="https://chirps.cc/embed.js" async></script>

Option B: Headless-Integrationen (Backend / CRMs / Bots)

Wenn Sie einen benutzerdefinierten Client erstellen (wie einen Discord-Bot, eine Telegram-Integration oder eine native iOS-App), werden Sie die Web-Einbettung NICHT verwenden. Stattdessen interagieren Sie direkt mit dem Endpunkt „/api/chat“.

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

Wichtig: Headless- und Server-zu-Server-Aufrufe müssen Authorization: Bearer <YOUR_CHIRPS_API_KEY> enthalten. Nur das installierte Browser-Widget verwendet den öffentlichen, an die Herkunft gebundenen Ablauf. API-Schlüssel gehören niemals in Frontend-JavaScript.

{

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

*(Unterstützt auch „multipart/form-data“ mit einem „file“-Feld für Anhänge, wenn „fileUploadEnabled“ wahr ist.*

Modus 1: Standard-JSON-Antwort (Standard)

Indem Sie eine POST-Anfrage an „/api/chat“ senden (ohne den Stream-Parameter), warten Sie auf die vollständige KI-Antwort und erhalten ein Standard-JSON-Objekt.

{

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

*(Wenn „is_active_agent: true“ zurückgegeben wird, hat ein Mensch den Chat übernommen und „message“ ist „null“.)*

Modus 2: Streaming von vom Server gesendeten Ereignissen (?stream=true)

Durch Anhängen von „?stream=true“ an die URL erhalten Sie einen Server-Sent Events (SSE)-Stream in Echtzeit. Ihr Code sollte auf diese spezifischen Ereignistypen warten:

• `event: token`: Enthält {"text": "chunk"}. Wird für jeden Teil des Antworttextes der KI ausgelöst.
• `event: status`: Enthält {"text": "Searching knowledge base..."}. Stellt den Ausführungsstatus des Backend-Tools dar.
• `event: done`: Enthält {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}. Wird ausgelöst, wenn die Generierung vollständig abgeschlossen ist.
• `event: error`: Enthält {"error": "Error message"}. Wird ausgelöst, wenn Ratenbegrenzungen oder Fehler auftreten.

Live-Übernahme-Endpunkte

GET /api/chat/sessions

Rufen Sie historische Sitzungen ab.

POST /api/chat/toggle-agent

Unterbrechen Sie die KI, damit der Mensch sie übernimmt. Nutzlast: { "sessionId": "...", "isActive": true }

POST /api/chat/agent-message

Senden Sie eine menschliche Nachricht. Nutzlast: { "sessionId": "...", "message": "..." }

Complete chat response contract

{
  "message": "I've opened the booking calendar for you.",
  "messageId": "uuid",
  "conversationId": "uuid",
  "artifacts": [
    {
      "type": "booking",
      "title": "Book a consultation"
    }
  ],
  "sources": []
}

A human takeover returns { message: null, conversationId, is_active_agent: true }. A streaming request can therefore return JSON before an SSE stream begins; check the response Content-Type.

Complete SSE event reference

Kernkonfiguration aktualisieren

Ändern Sie die Kerneinstellungen, die Persona und die Scraping-Grenzen des Assistenten.

{

  "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
  }
}

*Hinweis: Alle Felder sind optional. Senden Sie nur die Felder, die Sie aktualisieren möchten.*

Assistent löschen

DELETE /api/assistants/:id

Löscht den Assistenten dauerhaft und leitet die Löschung auf alle Wissensknoten, Konversationen und Nachrichten weiter. Wenn der Assistent nie vollständig eingerichtet wurde, wird das monatliche Erstellungskontingent zurückerstattet.

POST /api/phone-numbers/:subscriptionId/assign assigns an already-purchased Chirps phone subscription to an assistant. Send { "assistantId": "uuid" }; send { "assistantId": null } to unassign it. This endpoint does not purchase or provision a new number.

POST /api/assistants/:id/outbound – Ausgehenden Anruf auslösen. Nutzlast: { "phoneNumber": "+123...", "callReason": "Confirm the requested appointment", "conversationId": "optional-uuid" }

GET /api/leads?id=leadId – Details eines einzelnen Leads abrufen, einschließlich des vollständigen Gesprächsprotokolls.

Public lead response

Lead objects contain id, assistant_id, conversation_id, session_id, name, email, phone, status, notes, artifact_id, ai_score, ai_summary, form_data, created_at, and the assistant business name. Internal voice-confirmation/idempotency identifiers are never returned.

GET /api/bookings?id=bookingId – Details einer einzelnen Buchung abrufen, einschließlich des Konversationsprotokolls.

DELETE /api/bookings/cancel?id=bookingId - Storniert eine aktive Buchung. Fügen Sie &silent=true nur hinzu, wenn Ihre Integration die Ersatz-Stornierungs-E-Mail von Chirps bewusst unterdrücken soll.

POST /api/bookings/reschedule – Passen Sie eine Buchung an. Nutzlast: „{ "bookingId": "uuid", "newStartTime": "ISO-8601", "newEndTime": "ISO-8601" }`

Public booking response and time zones

Booking objects contain the public appointment, guest, status, notes, and timestamp fields plus business_timezone. Times are ISO-8601 instants; format them in the viewer's time zone while preserving the returned business zone for schedule context. Internal confirmation IDs, provider calendar-event IDs, and database range columns are omitted.

Rufen Sie die Abrechnungszyklusnutzung des Arbeitsbereichs, die Abonnementlimits und die Gesamtzahl der Assistenten ab. Hinweis: Bei Verwendung eines API-Schlüssels wird die Anfrage automatisch auf den Arbeitsbereich des API-Schlüssels beschränkt; Sie müssen keine „teamId“ angeben.

Antwort („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"
}

What belongs in the public developer API

These routes accept a scoped Chirps API key and enforce its workspace boundary. Dashboard-only billing/OAuth routes, browser widget callbacks, provider webhooks, cron jobs, and internal MCP routes are intentionally excluded.

Assistants

Knowledge and training

Widget, artifacts and connectors

Conversations, leads and bookings

Telephony and account