はじめに
自社で開発している Cognitia の Business API について、実際の呼び出し方と、レスポンス・利用量の数え方を技術的に解説します。現在は無料トライアル期間中で、請求は発生しません。ユーザーが自分のメモリ（メール、ファイル、チャット履歴など）をアプリに接続すると、アプリはそのユーザーについて質問（Ask）したり、構造化データを取り出したり（Retrieve）できます。
アカウント作成直後から 架空のサンプル人物 が用意されているので、実ユーザーなしで動作を確認できます。
1. 準備
- https://www.cognitia-ai.com/business/start でビジネスアカウントを作成（会社情報の入力は不要）
- ダッシュボードで API キー（
cog_biz_...）を発行し、環境変数に入れる - ダッシュボードのクイックスタートに表示されるサンプル人物の ID を控える
export COGNITIA_API_KEY=cog_biz_xxxxxxxx
export SAMPLE_USER_ID=xxxxxxxx # ダッシュボードに表示される ID
2. Ask：自然言語で質問する
curl -X POST https://www.cognitia-ai.com/api/marketplace/ask-query \
-H "Authorization: Bearer $COGNITIA_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"target_user_id\": \"$SAMPLE_USER_ID\", \"query\": \"What is this person working on, and how do they like to travel?\", \"include_evidence\": true}"
レスポンスの主なフィールド：
| フィールド | 内容 |
|---|---|
context |
回答本文（三人称） |
evidence |
include_evidence: true のときだけ返る。回答の根拠になった出典 |
usage.credits |
この呼び出しのクレジット数 |
usage.charge_usd |
正式課金時の想定金額（1クレジット = $0.002）。無料トライアル中は請求されません |
usage.input_tokens / output_tokens
|
Ask が実際に使ったトークン数 |
usage.dedup |
同じ質問の再送で、クレジットが計上されなかった場合に true
|
レスポンスヘッダーにも X-Credits、X-Charge、X-Funding と x-request-id が付きます。問い合わせのときは x-request-id を伝えてください。
3. Retrieve：構造化データを取り出す
import os, requests
res = requests.post(
"https://www.cognitia-ai.com/api/marketplace/retrieve-query",
headers={"Authorization": f"Bearer {os.environ['COGNITIA_API_KEY']}"},
json={"target_user_id": os.environ["SAMPLE_USER_ID"], "query": "upcoming travel", "limit": 20},
)
data = res.json()
print(len(data["entities"]), len(data["facts"]), len(data["edges"]))
Retrieve は entities、facts、edges を返します。limit の上限は 200 です。
4. 利用量の数え方
無料トライアル中は請求されませんが、レスポンスの usage には、正式課金で使う予定の数え方でクレジット数が記録されます。
-
Retrieve：返ってきたレコード数で決まります。20件まで 1 クレジット、以降 20 件ごとに +1、最大 10 クレジット（200件）。
limitは上限であって課金単位ではないので、limit: 200で 20 件しか返らなければ 1 クレジットです。 - Ask：実際に使った入力・出力トークンから計算します。最低料金はありません。社内の評価では、典型的な呼び出しは入力約 17k / 出力約 500 トークンで、2 クレジット（$0.004）程度でした。
- 重複除外：同じビジネス・同じユーザー・同じ質問は、60 分以内なら重複して計上しません。
-
入力の上限：Ask の
queryは 2,000 文字、Retrieve のqueryは 500 文字、リクエストボディは 16KB まで。超えると400/413で拒否します。
5. 実ユーザーを接続する
自社ユーザーを接続するときは、サーバーから partner/users を呼んで Connect 用リンクを受け取り、ユーザーをホスト済みの Connect ページに送ります。
await fetch('https://www.cognitia-ai.com/api/marketplace/partner/users', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.COGNITIA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
email: 'user@example.com',
external_user_id: 'your-user-id',
client_id: 'YOUR_CLIENT_ID',
return_url: 'https://your-app.example/cognitia/return',
providers: ['gmail', 'google-drive'],
}),
})
ユーザーは Connect ページでデータソースごとに「オフ / 抽出された事実のみ / 原文まで」を選びます。アプリ側から見えるのは、その範囲だけです。
おわりに
無料トライアル中なので、ここまですべて無料で試せます。API の仕様（MCP 契約・evidence オブジェクトなど）は Apache-2.0 のオープン仕様として公開しています。使ってみての感想や「ここが分かりにくい」「このデータソースが欲しい」といったご意見を、コメントでいただけると嬉しいです。