# API入門

<span data-t="appName">Your AI Connector</span> REST APIを使用すると、アカウント上で独自の統合を構築できます。連絡先の作成や検索、キャンペーン、FAQ、タスク、予定の管理、メッセージの送信、Webhookの登録、分析の読み取り、メッセージングチャネルの接続など、ダッシュボードでできるすべての操作をコードで実行できます。

ここはAPIドキュメントのハブページです。<span data-t="appName">Your AI Connector</span>をすでに組み込み統合機能を持つツールに接続している場合、APIは不要かもしれません。APIは、カスタム統合や大規模な自動化のためのものです。

::: note
**注:** これらのページは開発者向けに作成されています。開発者ではない場合は、このセクションを技術チームと共有してください。
:::


---

## ベースURL

すべてのリクエストは同じベースWebアドレスに送信されます。これらのドキュメント内のすべてのパスは、そのアドレスからの相対パスです。

```
https://api.youraiconnector.com/v1
```

つまり、キャンペーンのエンドポイントは`https://api.youraiconnector.com/v1/campaigns`、連絡先のエンドポイントは`https://api.youraiconnector.com/v1/contacts`のようになります。

すべてのリクエストは安全な接続（HTTPS）を使用する必要があります。通常のHTTPリクエストは拒否されます。

---

## APIキーの取得

APIアクセスは**有料機能**です。ご利用のプランに含まれていない場合、すべてのリクエストは以下の本文を含む`403`を返します。

```json
{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}
```

プランでAPIアクセスが有効になったら、ダッシュボードからキーを生成してください。詳細な手順は[APIアクセス](../integrations/api-access.md)に記載されています。簡単に説明すると、**設定 → インテグレーション → APIキー**に移動して、キーの生成または再生成を行います。「APIキー」はインテグレーション内の独立したセクションであり、Webhookとは別になっています。また、APIアクセスがプランで有効になっている場合にのみ表示されます。キーはパスワードと同様に扱い、アカウントへのフルアクセス権を与えるものとして管理してください。

---

## 認証

APIキーは4つの方法で送信できます。いずれの方法も、APIキー認証を受け入れるすべてのエンドポイントで機能します。

| メソッド | 方法 | 最適な用途 |
|---|---|---|
| クエリパラメータ | `?apiKey=YOUR_API_KEY` | クイックテスト、ブラウザURL、レガシー設定 |
| ヘッダー | `X-API-Key: YOUR_API_KEY` | 本番環境の統合 |
| Bearerヘッダー | `Authorization: Bearer YOUR_API_KEY` | 本番環境の統合 |
| Firebase IDトークン | `Authorization: Bearer <ID token>` | ファーストパーティアプリのセッションのみ |

本番環境では、キーがサーバーログやブラウザ履歴に残らないよう、ヘッダー形式のいずれかを使用することをお勧めします。クエリパラメータ形式は常に機能し、単発のテストには最も簡単です。

各メソッドの詳細、例、および使用時期に関するガイダンスについては、[認証](authentication.md)を参照してください。

---

## 最初のリクエスト

アカウント上のキャンペーンを一覧表示する、完全で動作可能な呼び出しの例を以下に示します。これはAPIキーを使用し、最新のキャンペーンから順に返します。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.campaigns);
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])
```

成功時のレスポンスは以下のようになります。

```json
{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}
```

---

## 成功およびエラーレスポンス

すべてのJSONレスポンスには `success` フラグが含まれているため、ステータスコードを解析することなく条件分岐を行うことができます。

成功時のレスポンスは `success: true` に加えて、そのエンドポイントのデータが含まれます（フィールド名は `campaigns`、`contacts`、`data` など、エンドポイントによって異なります）。

```json
{
  "success": true,
  "campaigns": []
}
```

失敗時のレスポンスは `success: false` となり、人間が判読可能な `error` メッセージと、HTTPステータスと一致する数値の `error_code` が含まれます。

```json
{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}
```

データを読み取る前に、必ず `success` （またはHTTPステータス）を確認してください。ステータスコードの完全な表や、大きな結果セットをページングする方法については、「[Errors & Pagination](errors-and-pagination.md)」を参照してください。

---

## レート制限

認証済みリクエストは、APIキーごとに**1分あたり300リクエスト**に制限されています。また、アカウント全体では**1分あたり1,200リクエスト**というより広い上限が設けられており、そのアカウントに対して行われたすべての認証済みリクエストがカウントされます。


いずれかの制限を超えた場合、`429`レスポンスが返されます：

```json
{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}
```

少し待ってから再試行してください。また、`GET https://api.youraiconnector.com/v1/api-keys/usage` を使用して現在の使用状況をいつでも確認できます。これには、現在のウィンドウで使用したリクエスト数とリセット時刻が返されるため、クライアント側のスロットリングを構築する際に役立ちます。「[API Keys](api-keys.md)」を参照してください。

---

## リソースガイド

以下のリソースグループには、それぞれ正確なパス、リクエストフィールド、レスポンスの形式をまとめたガイドが用意されています。

| リソース | 対象範囲 |
|---|---|
| [AIエージェント](agents.md) | AIエージェントの作成と設定：設定、稼働時間、ナレッジ、タグ付けルール、ツール、メディア、ドラフト |
| [エントリーポイント](entry-points.md) | 新規会話に応答するAIエージェントの決定：チャネルのデフォルト設定、WhatsApp番号ごとのエージェント設定、キーワード、コメント、フォロワーのルール |
| [ブロードキャスト](broadcasts.md) | 連絡先リストへの単発送信の作成、価格設定、開始、一時停止、複製 |
| [キャンペーン](campaigns.md) | キャンペーンとそのボット構成の作成、更新、複製、有効化、アーカイブ、確認 |
| [連絡先](contacts.md) | 連絡先の作成、検索、一覧表示、更新、インポート、タグ付け、削除 |
| [FAQ](faqs.md) | AIアシスタントが使用するQ&Aエントリの管理、およびそれらとキャンペーンのリンク |
| [ナレッジベース](knowledge-base.md) | WebサイトやドキュメントのAIナレッジへのインポート、およびFAQのグループ化 |
| [タスク](tasks.md) | CRMタスク、ボードステージ、タスクタイプの作成と管理 |
| [メッセージ](messages.md) | アウトバウンドメッセージの送信と会話履歴の読み取り |
| [予約](appointments.md) | 予約の作成、変更、キャンセル、削除 |
| [チャネル](channels.md) | メッセージングチャネルの接続と切断、番号の購入、各チャネルで新規会話に応答するAIエージェントの設定 |
| [テンプレート](templates.md) | WhatsAppメッセージテンプレートの作成、送信、承認ステータスの確認 |
| [分析](analytics.md) | 日次メッセージイベント統計、クレジット使用量、AIコストの集計の確認 |
| [Webhook](webhooks.md) | リアルタイムのイベント通知を受信するためのエンドポイントの登録 |
| [チーム](team.md) | チームメンバー、招待、ロール、権限、部門の管理 |
| [APIキー](api-keys.md) | APIキーの確認、ローテーション、取り消し、レート制限の使用状況の確認、およびアクセス制限付きの追加キーの作成 |

### エージェント、エントリーポイント、ブロードキャスト

AIエージェント、エントリーポイント、ブロードキャストはすべて公開されているOpenAPI仕様に含まれているため、[APIエクスプローラー](reference.md)で正確なフィールドを確認し、ライブリクエストを実行できます。それぞれに専用のガイドがあります：[AIエージェント](agents.md)、[エントリーポイント](entry-points.md)、[ブロードキャスト](broadcasts.md)。


---

## Markdown形式でのドキュメントの閲覧

このドキュメントのすべてのページには、プレーンなMarkdown形式の対となるページが存在します。ページのアドレスの末尾に `/index.md` を追加してください。したがって、このページも `https://docs.youraiconnector.com/api/getting-started/index.md` で利用可能であり、Webページではなくプレーンテキストとして取得されます。AIアシスタントにページを貼り付けたり、スクリプトに取り込んだりする場合に便利です。

全体を確認するには、公開しているすべてのページが一覧表示されている `https://docs.youraiconnector.com/sitemap.xml` から始めてください。ドキュメントは意図的に検索エンジンから除外されているため、コードからアクセスする場合は、これらのアドレスを直接取得する方法が推奨されます。

現時点では、キーで保護されたドキュメントエンドポイントや一括ダウンロード機能はありません。Markdown形式のページとサイトマップがインターフェースのすべてであり、どちらもAPIキーを必要としません。

---

## 次のステップ

- [認証](authentication.md) — 統合に適した認証方法を選択します。
- [エラーとページネーション](errors-and-pagination.md) — 失敗の処理と結果のページネーションを行います。
- [APIアクセス](../integrations/api-access.md) — キーを生成し、動作例を確認します。