チャットAPI

あなたのマインドにメッセージを送り、AI生成の応答を受け取ります。チャットAPIは、ステートレスな完了とステートフルなマルチターン会話の両方をサポートし、自動的に履歴を管理します。

ステートフルチャット（推奨）

サーバーが履歴、コンテキスト圧縮、ロールアップサマリーを自動的に管理する永続的な会話を作成します。各リクエストで完全なメッセージ履歴を送信する必要はありません。

チャットの作成

マインドにリンクされた新しいステートフル会話を作成します。

エンドポイント: POST /api/v1/chats

空でない選択を mindId、mindIds、audienceIds のいずれか一つだけ指定してください。複数を組み合わせると 400 になります。空の任意配列は単一 Mind の指定を上書きしません。UUID の大文字・小文字と重複は無視されます。チャット作成の JSON はエスケープを含め最大 1 MiB です。超過するとデータベース操作やプラン権限確認の前に 413 が返ります。応答は非公開でキャッシュされません。

ヘッダー:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

リクエストボディ:

{
  "name": "My Conversation",
  "mindId": "your-mind-id"
}

レスポンス (201):

{
  "data": {
    "id": "601af953-3837-49c1-a31e-4fdbfa82ac04",
    "name": "My Conversation",
    "description": null,
    "createdAt": "2026-04-04T12:45:24.078Z",
    "minds": [
      {
        "id": "4774888e-0a03-40d7-979b-39b47c4c049c",
        "name": "Ada Lovelace",
        "discipline": "mathematician and computer scientist"
      }
    ]
  }
}

メッセージを送信

既存のチャットにメッセージを送信します。サーバーは自動的に会話履歴、コンテキストウィンドウの圧縮、ロールアップサマリーを処理します。

エンドポイント: POST /api/v1/chats/{chatId}/messages

単一・複数Mindのチャットは、各Mindに保存されたknowledge_onlyポリシーとワークスペースのWeb調査制限に従います。制限されたMindは現在の質問、学習済みペルソナ、検索された関連Mind知識を使い、内部ツール、クライアントツール、過去のチャット文脈、コピーされたStudyの資料を回答の文脈に含めません。関連する根拠を取得できた場合はmetadata.knowledgeRetrieval.statusがgroundedになり、根拠がない場合や検索に失敗した場合はfallbackになります。複数Mindの回答では、各messages[]項目のmetadataに個別の状態が示されます。

ワークスペースのWeb調査権限はknowledge_onlyとは別です。無効にするとWeb検索とリンク解析ツールが除外されますが、autoを使うMindでは提供された資料と会話履歴が保持されます。上記の回答文脈の制限は、knowledge_onlyを使うMindに適用されます。

ローリングメモリは、コピーされた Study の文脈によって変わり得る配列位置ではなく、最後に要約したメッセージ ID の次から再開します。生成された要約行は会話の発言から除外されますが、所有者が記入したシステムメモは v1 チャットで引き続き利用できます。別のリクエストが参照元の保存済み要約を変更した場合、そのバックグラウンド結果は破棄されます。

ローリング要約が失敗した場合や要約本文が空の場合、フォールバックは以前の要約と有効な保存済み事実を引き継ぎ、新しい会話区間の短い抜粋を追加します。 フォールバックは1回の更新で新たに対象となる最大30件のメッセージを抜粋し、その範囲までのみ処理済みとします。残りは後の更新対象として保持されます。リクエストの圧縮では保存済みのメッセージIDを基準に処理済みの抜粋を繰り返さず、最近のメッセージ、優先される証拠、コピーされたStudyの文脈を保持します。

モデレーターは Mind ID で参加者を識別します。表示名が同じ Mind も別々の候補として扱われ、発言回数の上限と連続発言の防止は ID ごとに適用されます。すべての Mind が回答する前に、モデレーターが議論を終了する場合があります。

予期しない生成失敗はプロバイダーの内部情報を含まない汎用の 500 を返し、失敗した回答分の予約済み枠の返還を要求します。すでに生成された回答や保存されたメッセージは取り消されません。モデルの機能に関する明示的な拒否は data.errorType: "unsupported_model_capability" 付きの 400 のままです。複数 Mind のチャットでは、任意のバックグラウンド要約が保存済みの回答を遅延させたり、エラー応答に変えたりすることはありません。

メッセージの JSON も最大 1 MiB です。超過時はデータベース操作やプラン権限確認の前に 413 を返します。応答は非公開でキャッシュされません。投稿できるのは所有者のみです。管理対象ワークスペースでは現在のワークスペースと関連する Mind/Audience の権限を毎回確認し、取り消されたアクセスには保存や課金の前に 404 を返します。

以下の応答例は単一 Mind 用です。複数 Mind のチャットは messages[]、Study チャットは outputData を返します。role: "system" は生成やメッセージ枠の消費なしで文脈メモを保存し、{ messageId, role: "system" } を返します。

ヘッダー:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

リクエストボディ:

{
  "content": "What are the latest advancements in solar panel technology?"
}

ステートフルチャットモデルの選択は、この順序で行われます: リクエストごとのオーバーライド、次にチームの設定された優先プロバイダー、最後に製品のデフォルト。このエンドポイントでは、部分的なオーバーライドは400 Bad Requestで拒否されます; modelとproviderの両方を送信するか、両方を省略してください。

レスポンス:

{
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency...",
  "messageId": "cmnkbsddh00033v01ptk9t4et"
}

マルチターンの例

ステートフルチャットでは、毎回新しいメッセージを送信するだけです。サーバーはすべてを記憶します：

# Step 1: Create a chat
CHAT=$(curl -s -X POST "https://getminds.ai/api/v1/chats" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Research Session", "mindId": "your-mind-id" }')

CHAT_ID=$(echo $CHAT | jq -r '.data.id')

# Step 2: Send messages (server manages history automatically)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "What are the top marketing trends?" }'

# Step 3: Follow up (the mind remembers the previous exchange)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Which of those would work best on a small budget?" }'

内部の動作:

• すべてのメッセージはデータベースに保存されます
• 履歴が長い単一Mindのチャットでは、直近8件のメッセージを全文のまま保持します
• 古い発言には利用可能な保存済み要約を使い、未処理のメッセージの抜粋を加えます
• 要約では詳細が失われます。非常に長い履歴や大きなメッセージは、モデルのコンテキスト上限に達することがあります。

チャットを削除

DELETE /api/v1/chats/{chatId}

所有者のみがチャットとメッセージを完全に削除できます。Minds と Audiences は保持されます。成功時は本文なしの 204 が返るため、JSON として解析しないでください。認証情報がないか無効な場合は 401、他の所有者のチャットは 403、存在しないチャットは 404 です。最終書き込み前に削除または移譲された場合も 404 になります。削除の応答には Cache-Control: private, no-store が設定されます。

ステートレス完了

単一リクエスト用、または会話履歴を自分で管理したい場合に使用します。

メッセージを送信

マインドにメッセージを送り、応答を受け取ります。

エンドポイント: POST /api/v1/minds/{mindId}/completion

ヘッダー:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

リクエストボディ

{
  "messages": [
    {
      "role": "user",
      "content": "What are the latest advancements in solar panel technology?"
    }
  ]
}

パラメータ

レスポンス

{
  "messageId": "msg_550e840029b141d4a716446655440000",
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency, bifacial panels that capture light from both sides, and integrated storage systems...",
  "metadata": {
    "ragCitations": [
      {
        "id": "abc123",
        "displaySource": "Mind knowledge",
        "similarity": 0.89
      }
    ]
  }
}

単一メッセージの例

単一の質問をする：

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top 3 marketing trends for 2025?"
      }
    ]
  }'

マルチターン会話

以前のメッセージを含めて会話のコンテキストを維持します：

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top marketing trends?"
      },
      {
        "role": "assistant",
        "content": "The top trends are AI personalization, short-form video, and community building..."
      },
      {
        "role": "user",
        "content": "How can I implement AI personalization on a budget?"
      }
    ]
  }'

マルチターン会話のヒント:

• 各リクエストに完全な会話履歴を含める
• 順序が重要: メッセージは時系列であるべき
• userとassistantロールを交互に使用する
• 最後のメッセージは常にuserからであるべき

ファイル添付

ファイル、文書、画像、リンクを添付して、Mindsにコンテキストを提供します。Mindsは処理されたコンテンツを会話の一部として受け取ります。

ファイルの添付

ユーザーメッセージのmetadata.attachedFiles配列を介してファイルを追加します：

ステートレスな補完では、自分のアップロード、有効な署名付きチャットファイルURL、またはアップロードした人のStudyで共有されたコンテキストを使用してください。アクセス権のないワークスペースファイルは 403 Upload access denied を返します（ストリーミングではエラーフレーム）。外部HTTP(S) URLは元のアクセストークンを使用し、任意のストレージパスから署名を再発行することはありません。例の your-user-id を自分のユーザーIDに置き換え、アップロードエンドポイントが返したパスを使用してください。

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Please review this document and summarize the key points",
        "metadata": {
          "attachedFiles": [
            {
              "url": "https://example.com/quarterly-report.pdf",
              "name": "Q4 2025 Report",
              "type": "application/pdf"
            },
            {
              "path": "chat/your-user-id/meeting-notes.docx",
              "name": "Strategy Meeting Notes"
            }
          ]
        }
      }
    ]
  }'

添付形式

各添付オブジェクトは次のことをサポートします：

注意: urlまたはpathのいずれかを提供してください。両方は不可です。

サポートされているファイルタイプ

文書:

• PDF (.pdf) - テキスト抽出 + スキャンページのOCR
• Word (.docx) - 完全なテキスト抽出
• テキスト (.txt, .md) - 直接のテキストコンテンツ
• CSV/Excel (.csv, .xlsx) - テーブル抽出

画像:

• PNG, JPG, WEBP - OCR + ビジュアル分析
• 画像理解のためのビジョン機能

外部URL:

• Firecrawlで取得されたウェブページ（JSレンダリング + スクリーンショット）
• 自動マークダウン変換

処理

ファイルはマインドに送信される前に自動的に処理されます：

1. ダウンロード - URLまたはSupabaseストレージからファイルを取得
2. 抽出 - コンテンツを抽出（PDFからのテキスト、画像からのOCRなど）
3. 注入 - 処理されたコンテンツが会話のコンテキストに追加されます
4. 応答 - マインドはあなたのメッセージとファイルコンテンツの両方を確認します

処理制限:

• タイムアウト: 1ファイルあたり30秒
• ファイルは並行して処理されます
• 失敗したファイルには優雅なフォールバックメッセージが表示されます

複数ファイルの例

{
  "messages": [
    {
      "role": "user",
      "content": "Compare these two proposals and recommend which one to pursue",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/proposal-a.pdf",
            "name": "Proposal A - Cloud Migration",
            "type": "application/pdf"
          },
          {
            "url": "https://example.com/proposal-b.pdf",
            "name": "Proposal B - On-Prem Upgrade",
            "type": "application/pdf"
          },
          {
            "path": "chat/your-user-id/budget-analysis.xlsx",
            "name": "Budget Comparison"
          }
        ]
      }
    }
  ]
}

会話履歴におけるファイル添付

ファイル添付を伴う会話を続ける際は、履歴に添付された元のメッセージを含めてください：

{
  "messages": [
    {
      "role": "user",
      "content": "Analyze this sales data",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/sales-q4.csv",
            "name": "Q4 Sales Data"
          }
        ]
      }
    },
    {
      "role": "assistant",
      "content": "Based on the Q4 sales data, I can see that revenue increased by 23% compared to Q3..."
    },
    {
      "role": "user",
      "content": "What were the top 3 performing products?"
    }
  ]
}

注意: ファイルは最初に添付されたときにのみ処理されます。同じ会話内の後続メッセージは、すでに処理されたコンテンツを参照します。

ウェブリンク

ウェブページや外部コンテンツには、urlフィールドを使用します：

{
  "messages": [
    {
      "role": "user",
      "content": "Summarize the key findings from this research paper",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://arxiv.org/pdf/2103.12345.pdf",
            "name": "AI Research Paper",
            "type": "application/pdf"
          }
        ]
      }
    }
  ]
}

特にウェブページの場合:

• JavaScriptが多用されるサイトはFirecrawlでレンダリングされます
• ビジュアルコンテキストのためにスクリーンショットがキャプチャされます
• コンテンツはクリーンなマークダウンに変換されます

エラーハンドリング

ファイル処理が失敗した場合:

• マインドはファイルが添付されたが処理が失敗したことを示すフォールバックメッセージを受け取ります
• 会話は通常通り続きます
• タイムアウトエラーは[Processing timeout - file may be too large]を表示します
• その他のエラーは[Processing failed - file uploaded but analysis unavailable]を表示します

これにより、マインドは処理が失敗しても試みられた添付について認識します。

初期メッセージ（挨拶）

空のメッセージ配列またはメッセージがない場合、マインドが自己紹介をします：

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": []
  }'

レスポンス:

{
  "content": "Hi! I'm Sarah, a marketing director with 15 years of experience in B2B SaaS. I specialize in growth marketing and data-driven strategies. What can I help you with today?"
}

モデルオーバーライド

ステートレス完了リクエストで使用されるAIモデルをオプションでオーバーライドするには、modelパラメータを渡します。これはベンチマーク、コスト最適化、または異なるモデルの動作をテストするのに便利です。ステートフルチャットとパネルエンドポイントは、より厳格なオーバーライド検証を使用します: modelとproviderの両方を一緒に送信してください。

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are your thoughts on sustainable packaging?"
      }
    ],
    "model": "gpt-6-luna"
  }'

modelが指定されていない場合、サーバーのデフォルトが使用されます。

プロバイダー

上記の表にあるモデルのいずれかを渡してください。廃止された ID は転送されます（下記参照）。それ以外のモデルは 400 Bad Request を返します。プロバイダーは一般的なモデル名のプレフィックスから自動検出されます（claude- → Anthropic、gemini- → Google、gpt-/o1/o3/o4 → OpenAI）。

Your own model

ファインチューニングしたモデルやセルフホストのモデルを使うには、チーム管理者がそのモデルをチームモデル接続（OpenAI Chat Completions、OpenAI Responses、または Anthropic Messages プロトコル）として追加し、検証します。その後、model と provider の代わりに接続の ID と現在のリビジョンを送信してください：

{
  "messages": [...],
  "modelConnection": { "id": "3f6c1e2a-5b7d-4c1e-9a0f-2d8e4b6a1c90", "revision": 3 }
}

GET /api/v1/model-connections は、チームの接続をリビジョンと検証済みの機能とともに一覧表示します。接続にはテキストとストリーミングが必要です。response_format を送信する場合は構造化出力、リクエストでツールを使用する場合はツール呼び出しも必要です。エンドポイントが失敗した場合、リクエストも失敗します。Minds が自社のモデルに切り替えることはありません。画像やその他のメディアは MODEL_CONNECTION_MEDIA_UNVERIFIED で拒否されます。ステートフルチャットのメッセージ（/chats/{chatId}/messages）は接続を受け付けません。

構造化出力

特定のスキーマに一致するJSONレスポンスを保証するために、response_formatパラメータを使用してリクエストします。これはOpenAIスタイルの構造化出力パターンに従い、会話から構造化データを抽出するのに便利です。

JSONスキーマモード

モデルにスキーマに一致する有効なJSONを出力させます：

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Analyze the sentiment of this text: I love this product, it exceeded all my expectations!"
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "sentiment_analysis",
        "description": "Sentiment analysis result",
        "schema": {
          "type": "object",
          "properties": {
            "sentiment": {
              "type": "string",
              "enum": ["positive", "negative", "neutral"]
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "keywords": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["sentiment", "confidence", "keywords"]
        }
      }
    }
  }'

レスポンス:

{
  "content": "{\"sentiment\": \"positive\", \"confidence\": 0.95, \"keywords\": [\"love\", \"exceeded\", \"expectations\"]}",
  "parsed": {
    "sentiment": "positive",
    "confidence": 0.95,
    "keywords": ["love", "exceeded", "expectations"]
  }
}

JSONオブジェクトモード

スキーマ検証なしでJSON出力を強制します：

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "List 3 marketing ideas as JSON"
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'

レスポンス形式タイプ

JSONスキーマフィールド

サポートされているスキーマ機能

次のJSONスキーマ機能がサポートされています：

• タイプ: string, number, integer, boolean, array, object, null
• 制約: enum, minimum, maximum, minLength, maxLength, minItems, maxItems
• 構造: properties, required, items, additionalProperties
• メタデータ: description（モデルをガイドするために使用）

注意事項

• ツール（RAG、ウェブ検索など）は構造化出力で機能します , マインドは構造化応答を生成する前に知識ベースを検索できます
• parsedフィールドには便利な解析されたJSONオブジェクトが含まれ、contentには生のJSON文字列が含まれます
• すべての主要プロバイダー（OpenAI、Anthropic、Google）は構造化出力をサポートしています
• 複雑なスキーマの場合、モデルの出力をガイドするためにdescriptionフィールドを追加することを検討してください

ツール呼び出し

マインドが会話中にカスタム関数を呼び出せるようにします。これはOpenAI互換の関数呼び出しパターンに従い、外部ツールやAPIでマインドの機能を拡張できます。

仕組み

1. ツールを定義: 名前、説明、JSONスキーマパラメータを持つツール定義を渡します
2. マインドが決定: マインドは会話に基づいてツールを呼び出すタイミングを決定します（またはtool_choiceで強制します）
3. APIがツール呼び出しを返す: レスポンスにはtool_callsが含まれ、ツール名と生成された引数が含まれます
4. ツールを実行: アプリケーションでツールを実行し、結果を取得します
5. 結果を返送: 次のメッセージにツール結果を含め、role: "tool"を使用します
6. マインドが応答: マインドはツール結果を最終応答に組み込みます

基本的な例

ツールを使用したリクエスト:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            },
            "units": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "Temperature units"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }'

レスポンス:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_abc123",
      "name": "get_weather",
      "arguments": {
        "city": "Berlin",
        "units": "celsius"
      }
    }
  ]
}

ツールを実行し、結果を返送:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      },
      {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_abc123",
            "name": "get_weather",
            "arguments": {
              "city": "Berlin",
              "units": "celsius"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": 18, \"condition\": \"partly cloudy\", \"humidity\": 65}"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["city"]
        }
      }
    ]
  }'

最終レスポンス:

{
  "content": "The current weather in Berlin is 18°C and partly cloudy, with 65% humidity."
}

ツール定義スキーマ

各ツールは次の構造に従う必要があります：

{
  "name": "tool_name",
  "description": "Clear description of when and how to use this tool",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "What this parameter does"
      }
    },
    "required": ["param1"]
  },
  "strict": true
}

必須フィールド:

オプションフィールド:

ツール選択モード

tool_choiceパラメータを使用して、マインドがツールを呼び出すタイミングと方法を制御します：

例:

// Let the mind decide
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "auto"
}

// Force a specific tool
{
  "messages": [...],
  "tools": [...],
  "tool_choice": {
    "name": "search_database"
  }
}

// Require at least one tool call
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "required"
}

並行ツール呼び出し

デフォルトでは、マインドは効率のために単一ターンで複数のツールを呼び出すことができます：

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "get_customer",
      "arguments": { "id": "CUST-001" }
    },
    {
      "id": "call_2",
      "name": "get_customer",
      "arguments": { "id": "CUST-002" }
    }
  ]
}

並行呼び出しを無効にし、逐次実行を強制するには：

{
  "messages": [...],
  "tools": [...],
  "parallel_tool_calls": false
}

ツールメッセージ形式

ツール結果を返送する際は、toolロールを使用します：

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"result\": \"success\", \"data\": {...}}"
}

ツール結果は、tool_callsを含む対応するアシスタントメッセージの後に送信します。返された呼び出しIDと名前を使用し、各結果は一度だけ返してください。不正な引数、不明な呼び出しID、一致しないツール名、重複した結果、クライアント側の結果の欠落は、生成前に400を返します。

内部ツールとユーザー工具

Mindsには自動的に実行されるサーバーサイドの組み込みツールがあります：

主な違い:

• 内部ツール: サーバーサイドで実行され、結果はcontentとmetadataに含まれます。tool_callsには決して返されません。
• ユーザー工具: あなたが実行するためにtool_callsに返されます。結果はtoolメッセージとして返送する必要があります。

内部ツールをオーバーライドまたは無効にすることはできません。ユーザー工具は追加的であり、マインドの機能を拡張します。

完全なマルチツール例

複数のカスタムツールを持つ法務アシスタントマインド：

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Create a new case for Schmidt vs. Mueller and search for similar precedents"
      }
    ],
    "tools": [
      {
        "name": "create_case",
        "description": "Create a new legal case in the system",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Case title (parties involved)"
            },
            "practice_area": {
              "type": "string",
              "enum": ["corporate", "litigation", "employment", "ip"],
              "description": "Legal practice area"
            },
            "client_id": {
              "type": "string",
              "description": "Client identifier"
            }
          },
          "required": ["title", "practice_area"]
        }
      },
      {
        "name": "search_precedents",
        "description": "Search legal database for similar cases",
        "parameters": {
          "type": "object",
          "properties": {
            "keywords": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Search keywords"
            },
            "practice_area": {
              "type": "string",
              "description": "Filter by practice area"
            },
            "max_results": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "description": "Maximum number of results"
            }
          },
          "required": ["keywords"]
        }
      }
    ],
    "parallel_tool_calls": true
  }'

並行ツール呼び出しを伴うレスポンス:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "create_case",
      "arguments": {
        "title": "Schmidt vs. Mueller",
        "practice_area": "litigation"
      }
    },
    {
      "id": "call_2",
      "name": "search_precedents",
      "arguments": {
        "keywords": ["Schmidt", "Mueller"],
        "practice_area": "litigation",
        "max_results": 10
      }
    }
  ]
}

ベストプラクティス

1. 明確な説明を書く: descriptionフィールドは重要です。各ツールをいつ、なぜ使用するかを具体的に記述してください。

   ❌ "description": "データベースを検索"
   ✅ "description": "キーワードと実務分野に基づいて類似のケースを検索するための法的先例データベースを検索"
   

2. パラメータの説明を使用: 各パラメータが何をするかをマインドに理解させます。

   "case_id": {
     "type": "string",
     "description": "CASE-YYYY-NNNN形式のユニークなケース識別子"
   }
   

3. 制約値のために列挙型を活用:

   "status": {
     "type": "string",
     "enum": ["pending", "active", "closed", "archived"]
   }
   

4. 検証制約を設定:

   "priority": {
     "type": "integer",
     "minimum": 1,
     "maximum": 5,
     "description": "優先度レベル（1=最低、5=最高）"
   }
   

5. 厳密モードを有効にする: strict: true（デフォルト）を維持して、マインドが有効な引数を生成するようにします。
6. 構造化されたツール結果を返す: ツール結果をJSON形式で使用して、解析を容易にします：

   {
     "role": "tool",
     "tool_call_id": "call_123",
     "content": "{\"success\": true, \"case_id\": \"CASE-2026-001\", \"created_at\": \"2026-03-30T23:00:00Z\"}"
   }
   

7. エラーを優雅に処理する: ツール結果にエラーの詳細を返します：

   {
     "role": "tool",
     "tool_call_id": "call_123",
     "content": "{\"success\": false, \"error\": \"ケースはすでに存在します\", \"error_code\": \"DUPLICATE_CASE\"}"
   }
   

制限事項

• リクエストごとに最大128ツール
• ツール名はユニークでなければならず、内部ツール名と衝突してはなりません
• ツール実行はクライアント側で行われます , ツールの実行とセキュリティはあなたの責任です
• ツール結果はマインドが応答するために会話履歴に返送される必要があります

JSONスキーマサポート

parametersフィールドは標準のJSONスキーマ機能をサポートします：

タイプ:

• string, number, integer, boolean, array, object, null

検証:

• enum , 特定の値に制限
• minimum, maximum , 数値の範囲
• minLength, maxLength , 文字列の長さ
• minItems, maxItems , 配列のサイズ
• pattern , 正規表現の検証
• format , 文字列形式（例: "date-time", "email", "uri"）

構造:

• properties , オブジェクトプロパティ
• required , 必須フィールド
• items , 配列アイテムスキーマ
• additionalProperties , 追加プロパティの許可/不許可

高度な検証を伴う例:

{
  "name": "schedule_meeting",
  "description": "Schedule a meeting with a client",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "date": {
        "type": "string",
        "format": "date-time",
        "description": "Meeting date and time in ISO 8601 format"
      },
      "attendees": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        },
        "minItems": 1,
        "maxItems": 20
      },
      "duration_minutes": {
        "type": "integer",
        "minimum": 15,
        "maximum": 480,
        "description": "Meeting duration (15-480 minutes)"
      }
    },
    "required": ["title", "date", "attendees"]
  }
}

仕組み

1. コンテキストの読み込み

メッセージを送信すると、マインドは：

• システムプロンプトと設定を読み込みます
• 関連情報を自動的に知識ベースから検索します
• 会話履歴を考慮します

2. 処理

マインドは：

• あなたのメッセージをコンテキストで分析します
• 取得した知識に基づいて応答を生成し、引用を含めます
• 必要に応じて追加のツール（ウェブ検索、画像生成など）にアクセスします
• 自身の個性に沿った応答を形成します

3. 応答生成

マインドは：

• 専門知識を反映した応答を生成します
• 知識ベースやウェブソースを使用する際には引用を含めます
• オプションのメタデータ（引用、画像など）を含むメッセージを返します

メタデータ

レスポンスには追加のメタデータを含めることができます：

画像

マインドが画像を生成または表示する場合：

{
  "content": "Here are some logo concepts...",
  "metadata": {
    "images": [
      {
        "id": "img_123",
        "url": "https://...",
        "filename": "Logo Concept 1",
        "description": "Modern minimalist logo with blue gradient",
        "source": "generated"
      }
    ]
  }
}

知識引用

マインドが知識ベースやウェブ検索から情報を取得する場合：

{
  "content": "Based on recent research, solar panel efficiency has improved significantly...",
  "metadata": {
    "ragCitations": [
      {
        "id": "9bf44ab0-9d83-42ec-b941-c0ab7610e949",
        "displaySource": "Mind knowledge",
        "similarity": 0.85
      },
      {
        "id": "external-web-123",
        "displaySource": "https://example.com/solar-research",
        "similarity": 0.92
      }
    ]
  }
}

引用フィールド:

• id - ソースのユニーク識別子
• displaySource - 人間が読めるソース名またはURL
• similarity - クエリに対するソースの適合度を示す関連スコア（0-1）

Mindsは応答する前に自動的に知識ベースを検索し、特定のソースに基づいて回答を根拠づける際には引用を含めます。

アクセス制御

あなたは以下のMindsとチャットできます：

• 所有 - あなたが作成したMinds
• アクセス権がある - チームメンバーによって共有されたMinds
• メンバーである - あなたが所属するチームワークスペース内のMinds
• 公開Minds - 公開でアクセス可能なMinds

無許可のマインドにアクセスしようとすると、次のようになります：

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

レスポンス形式

テキストレスポンス

ほとんどのレスポンスはプレーンテキストです：

{
  "content": "Based on current trends, I recommend focusing on..."
}

構造化レスポンス

一部のマインドは構造化されたコンテンツを返す場合があります：

{
  "content": "Here's my analysis:\n\n1. Trend: AI Personalization\n   - Impact: High\n   - Timeline: 6-12 months\n\n2. Trend: Short-form Video\n   - Impact: Very High\n   - Timeline: Immediate"
}

メタデータのみの空レスポンス

時にはメタデータのみが返されることがあります（例: 画像生成の場合）：

{
  "content": "",
  "metadata": {
    "images": [...]
  }
}

ベストプラクティス

具体的にする

❌ "Tell me about marketing"
✅ "What are the most cost-effective digital marketing channels for a B2B SaaS startup with a $5K monthly budget?"

コンテキストを提供する

✅ "We're launching a sustainable fashion brand targeting Gen Z. What social media strategy would you recommend?"

フォローアップを使用する

会話メモリを活用してください：

User: "What are the top trends?"
Assistant: "The top trends are..."
User: "Which of these would work best for a small budget?"
Assistant: "For a small budget, I'd focus on..."

知識を参照する

アップロードした知識を参照してください：

✅ "Based on our brand guidelines, what tone should we use for this campaign?"

エラーレスポンス

400 Bad Request

スパークIDが欠落または無効です：

{
  "statusCode": 400,
  "statusMessage": "Mind ID is required"
}

サポートされていないプロバイダー：

{
  "statusCode": 400,
  "statusMessage": "Unsupported provider: 'invalid'. Supported providers: openai, anthropic, google."
}

プロバイダーなしの曖昧なモデル名：

{
  "statusCode": 400,
  "statusMessage": "Cannot auto-detect provider for model 'my-model'. Please specify a 'provider' parameter (openai, anthropic, or google)."
}

401 Unauthorized

無効なAPIキー。

403 Forbidden

スパークへのアクセスが拒否されました：

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

404 Not Found

スパークが存在しません：

{
  "statusCode": 404,
  "statusMessage": "Mind not found"
}

使用ノート

• v1 APIは認証済みアカウントごとの設定可能な制限（既定で1分あたり300リクエスト）を適用します
• RateLimit-LimitとRateLimit-Remainingを読み、429後はRetry-Afterに従ってください
• 生成処理は負荷が高いため、並列completion数を制限してください

次のステップ

• レイテンシとパフォーマンスを理解する
• エラーとレート制限について学ぶ
• 最初のマインドを作成する
• 応答を向上させるために知識をアップロードする
• API概要を読む