チャットAPI

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

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

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

チャットの作成

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

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

ヘッダー:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

リクエストボディ:

{
  "name": "My Conversation",
  "sparkId": "your-spark-id"
}

レスポンス (201):

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

メッセージを送信

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

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

ヘッダー:

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", "sparkId": "your-spark-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?" }'

内部の動作:

• すべてのメッセージはデータベースに保存されます
• 最後の8メッセージが完全なコンテキストで送信されます
• 古いメッセージはロールアップLLMサマリーに圧縮されます
• 会話は数週間または数ヶ月にわたってコンテキスト制限に達することなく続けられます

ステートレス完了

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

メッセージを送信

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

エンドポイント: POST /api/v1/sparks/{sparkId}/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": "Spark knowledge",
        "similarity": 0.89
      }
    ]
  }
}

単一メッセージの例

単一の質問をする：

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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/sparks/spark-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配列を介してファイルを追加します：

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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": "uploads/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": "uploads/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/sparks/spark-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/sparks/spark-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-4o-mini"
  }'

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

プロバイダー

プロバイダーによってサポートされている任意のモデル文字列を渡すことができます。プロバイダーは一般的なモデル名のプレフィックスから自動検出されます（claude- → Anthropic、gemini- → Google、gpt-/o1/o3/o4 → OpenAI）。

曖昧な名前のモデルについては、providerを明示的に指定してください：

{
  "messages": [...],
  "model": "my-custom-fine-tune",
  "provider": "openai"
}

プロバイダーが特定できない場合、APIは400 Bad Requestエラーを返し、指定するように求めます。

構造化出力

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

JSONスキーマモード

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

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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/sparks/spark-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/sparks/spark-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/sparks/spark-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\": {...}}"
}

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

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

主な違い:

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

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

完全なマルチツール例

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

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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": "Spark 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": "Spark 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": "Spark not found"
}

使用ノート

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

次のステップ

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