究極の開発者 API ガイド

すべてのAPIエンドポイントは、AuthorizationヘッダーにChirps APIキーを必要とします。APIキーは、ダッシュボードの開発者セクションにあるAPIマネージャーから生成できます。

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

リクエスト例:

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

標準的なエラー処理

スコープと最小権限

各キーは選択されたスコープだけに制限されます。可能な限り読み取り専用キーを使い、連携ごとに別のキーを作成してください。書き込みスコープに対応する読み取り権限は自動では含まれません。

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.

アシスタントの一覧表示

APIキーのワークスペースに関連付けられたすべてのアシスタントのリストを取得します。

アシスタントの作成

POST /api/assistants

すべての基本設定を持つ新しいアシスタントを作成します。

{

  "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 /api/assistants/:id

アシスタントを完全に削除し、そのすべてのナレッジノードと履歴を連鎖的に削除します。ペイロードは不要です。

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

指定されたアシスタントの利用統計、総メッセージ数、獲得リード数、および一般的なエンゲージメント指標を取得します。range パラメータはオプションです（日数、最小7日、最大365日、デフォルト30日）。

期待されるレスポンス

{

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

ナレッジノードの管理

GET /api/assistants/:id/nodes - このアシスタントのすべてのナレッジノードを一覧表示します。

POST /api/assistants/:id/nodes - 新しいナレッジブロックを手動で挿入します。

{

  "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 - 既存のノードのコンテンツを変更するか、そのアクティブ状態を切り替えます。

{

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

DELETE /api/assistants/:id/nodes/:nodeId - ナレッジブロックを完全に削除します。

POST /api/assistants/:id/nodes/:nodeId/re-crawl - スクレイパーにこのノードに関連付けられたURLを再クロールさせ、そのコンテンツを更新するよう強制します。ペイロード: {}。

AIトレーニング

POST /api/assistants/:id/train - すべてのis_activeナレッジノードをコンパイルし、AIオーケストレーターを使用して新しいマスターシステムプロンプトを動的に合成します。ペイロード: {}。

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.

オプションA: ウェブ埋め込み (フロントエンド)

アシスタントを標準的なウェブサイト（WordPress、Shopify、Reactなど）に統合する最も簡単な方法です。埋め込みコードは完全に決定論的です。取得するためのエンドポイントは必要ありません。サイトの<head>にこれを追加するだけです。

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

オプションB: ヘッドレス連携 (バックエンド / CRM / ボット)

カスタムクライアント（Discordボット、Telegram連携、ネイティブiOSアプリなど）を構築している場合、ウェブ埋め込みは使用しません。代わりに、/api/chatエンドポイントと直接やり取りします。

POST /api/chat または /api/chat?stream=true

重要: ヘッドレスおよびサーバー間の呼び出しには Authorization: Bearer <YOUR_CHIRPS_API_KEY> が必要です。公開のオリジン制限フローを使うのは、設置済みブラウザーウィジェットだけです。APIキーをフロントエンドJavaScriptに入れないでください。

{

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

*(multipart/form-dataがtrueの場合、添付ファイル用にfileフィールドを持つfileUploadEnabledもサポートします。)*

モード1: 標準JSONレスポンス (デフォルト)

/api/chatにPOSTリクエストを送信する（ストリームパラメーターなしで）と、完全なAI応答を待ち、標準のJSONオブジェクトを受け取ります。

{

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

*(is_active_agent: trueが返された場合、人間がチャットを引き継いでおり、messageはnullになります。)*

モード2: サーバー送信イベントストリーミング (?stream=true)

URLに?stream=trueを追加すると、リアルタイムのサーバー送信イベント（SSE）ストリームを受信します。コードは以下の特定のイベントタイプをリッスンする必要があります。

• `event: token`: {"text": "chunk"}を含みます。AIの応答テキストの各チャンクに対して発火します。
• `event: status`: {"text": "Searching knowledge base..."}を含みます。バックエンドツールの実行状態を表します。
• `event: done`: {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}を含みます。生成が完全に完了したときに発火します。
• `event: error`: {"error": "Error message"}を含みます。レート制限またはエラーが発生した場合に発火します。

ライブ引き継ぎエンドポイント

GET /api/chat/sessions

過去のセッションを取得します。

POST /api/chat/toggle-agent

人間による引き継ぎのためにAIを一時停止します。ペイロード: { "sessionId": "...", "isActive": true }

POST /api/chat/agent-message

人間のメッセージを送信します。ペイロード: { "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

コア設定の更新

アシスタントのコア設定、ペルソナ、およびスクレイピング範囲を変更します。

{

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

*注: すべてのフィールドはオプションです。更新したいフィールドのみを送信してください。*

アシスタントの削除

DELETE /api/assistants/:id

アシスタントを完全に削除し、すべてのナレッジノード、会話、メッセージに削除をカスケードします。アシスタントが完全に設定されていなかった場合、月間作成クォータが返金されます。

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 - 発信をトリガーします。 Payload: { "phoneNumber": "+123...", "callReason": "Confirm the requested appointment", "conversationId": "optional-uuid" }

GET /api/leads?id=leadId - 完全な会話トランスクリプトを含む、単一リードの詳細を取得します。

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 - 会話のトランスクリプトを含む、単一の予約の詳細を取得します。

DELETE /api/bookings/cancel?id=bookingId - 有効な予約をキャンセルします。Chirpsの代替キャンセルメールを連携側で意図的に抑止する場合に限り、&silent=true を追加してください。

POST /api/bookings/reschedule - 予約を調整します。ペイロード: { "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.

ワークスペースの請求サイクル使用状況、サブスクリプションプランの制限、およびアシスタントの総数を取得します。注: APIキーを使用する場合、リクエストは自動的にAPIキーのワークスペースにスコープされるため、teamIdを提供する必要はありません。

レスポンス (`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