API

APIを使うために用意するもの

• APIを使うためには以下の3つが必要です。

1. API key
2. team_id
3. assistant_id(bot_id)

1. API keyの取得方法

1. 右上のチームのアイコンから歯車マークをクリックする。

2. サイドバーのAPI設定をクリックし、API keyを取得する。「再生成」をクリックするとAPI keyが再生成される。

2. team_idの取得方法

1. API keyの場合と同様に歯車マークをクリックする

2. クリックで遷移した「チーム基本設定」ページから取得できる

3. assistant_id(bot_id)の取得方法

1. アシスタントの設定画面に入るとAPI連携の部分から取得できる。

API仕様

共通仕様

• Base Path: /api/v1
• 認証: Authorization: Bearer <TEAM_API_KEY>
• Content-Type:
  • JSON API: application/json
  • ファイルアップロード API: multipart/form-data
• レート制限:
  • chat-agent: 600 requests / minute
  • search / document / assistant: 600 requests / minute

共通エラー

• 400 Bad Request: リクエスト不正（必須不足・形式不正）
• 403 Forbidden: 認証エラーまたは team_id 不一致
• 404 Not Found: assistant_id や document_id が存在しない
• 429 Too Many Requests: レート制限超過

---

1) POST /api/v1/chat-agent/

チャット応答を取得します。thread_id を省略すると新規スレッドが作成されます。

Request (JSON)

{
  "assistant_id": 123,
  "message": "こんにちは",
  "thread_id": 456,
  "stream": false
}

• assistant_id (required, integer)
• message (required, string, max 100000 chars)
• thread_id (optional, integer)
• stream (optional, boolean, default: false)

Response 200 (stream=false)

{
  "event": "lookup_answer",
  "data": {
    "assistant_id": 123,
    "thread_id": 456,
    "message": "こんにちは",
    "answer": "お問い合わせありがとうございます。"
  }
}

cURL

curl -X POST "$BASE_URL/api/v1/chat-agent/" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": 123,
    "message": "こんにちは",
    "stream": false
  }'

---

2) POST /api/v1/search

アシスタントに紐づくナレッジからセマンティック検索を実行します。

Request (JSON)

{
  "team_id": 1,
  "assistant_id": 123,
  "query": "料金プラン",
  "top_k": 5
}

• team_id (required, integer)
• assistant_id (required, integer)
• query (required, string, max 1000 chars)
• top_k (optional, integer, 1-100, default: 5)

Response 200

{
  "results": [
    {
      "document_id": 1001,
      "type": "URL",
      "content": "プランの詳細..."
    }
  ]
}

cURL

curl -X POST "$BASE_URL/api/v1/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": 1,
    "assistant_id": 123,
    "query": "料金プラン",
    "top_k": 5
  }'

---

3) POST /api/v1/documnt/url

注意: 実際の有効なエンドポイントは POST /api/v1/document/url です。

指定 URL をクロールしてドキュメントを追加します。

Request (JSON)

{
  "team_id": 1,
  "assistant_id": 123,
  "url": "https://example.com/help"
}

• team_id (required, integer)
• assistant_id (required, integer)
• url (required, http/https)

Response 201

{
  "document_id": 1002
}

cURL

curl -X POST "$BASE_URL/api/v1/document/url" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": 1,
    "assistant_id": 123,
    "url": "https://example.com/help"
  }'

---

4) POST /api/v1/document/qa

Q&A 形式のドキュメントを追加します。

Request (JSON)

{
  "team_id": 1,
  "assistant_id": 123,
  "question": "営業時間は？",
  "answer": "平日 9:00-18:00 です。"
}

• team_id (required, integer)
• assistant_id (required, integer)
• question (required, string, max 1000 chars)
• answer (required, string, max 5000 chars)

Response 201

{
  "document_id": 1003
}

cURL

curl -X POST "$BASE_URL/api/v1/document/qa" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": 1,
    "assistant_id": 123,
    "question": "営業時間は？",
    "answer": "平日 9:00-18:00 です。"
  }'

---

5) POST /api/v1/document/file

ファイルをアップロードしてドキュメントを追加します。

Request (multipart/form-data)

• team_id (required)
• assistant_id (required)
• name (required, max 256 chars)
• file (required)

許可拡張子:

• pdf, doc, docx, pptx, html, json, csv, md, tex, txt

Response 201

{
  "document_id": 1004
}

cURL

curl -X POST "$BASE_URL/api/v1/document/file" \
  -H "Authorization: Bearer $API_KEY" \
  -F "team_id=1" \
  -F "assistant_id=123" \
  -F "name=利用規約" \
  -F "file=@./terms.pdf"

---

6) DELETE /api/v1/document

ドキュメントを1件削除します。

Request (JSON)

{
  "team_id": 1,
  "assistant_id": 123,
  "document_id": 1004
}

• team_id (required, integer)
• assistant_id (required, integer)
• document_id (required, integer)

Response 200

{
  "document_id": 1004
}

cURL

curl -X DELETE "$BASE_URL/api/v1/document" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": 1,
    "assistant_id": 123,
    "document_id": 1004
  }'

---

7) PUT /api/v1/assistant

アシスタントの指示文（instruction）を更新します。

Request (JSON)

{
  "team_id": 1,
  "assistant_id": 123,
  "instruction": "回答は必ず日本語で、簡潔に。"
}

• team_id (required, integer)
• assistant_id (required, integer)
• instruction (required, string, 空文字可)

Response 200

{
  "assistant_id": 123
}

cURL

curl -X PUT "$BASE_URL/api/v1/assistant" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": 1,
    "assistant_id": 123,
    "instruction": "回答は必ず日本語で、簡潔に。"
  }'

---

備考

• team_id は、Bearer APIキーに紐づく Team の ID と一致している必要があります。
• 不一致の場合は 403 Forbidden（{"error":"Forbidden"}）を返します。
• 認証ヘッダーがない場合は 403（{"error":"Unauthorized access"}）を返します。