Sparks API

AIマインド（エージェント）をプログラムで作成・管理します。Mindsは、特定の専門知識、パーソナリティ、ナレッジを持つカスタマイズ可能なAIアシスタントです。

ベースURL: https://getminds.ai/api/v1 または https://api.getminds.ai/v1

Sparkの取得

システムプロンプト、共有設定、ナレッジアイテム数などの詳細情報を含む単一のマインドを取得します。

エンドポイント: GET /api/v1/sparks/{sparkId}

ヘッダー:

Authorization: Bearer minds_your_api_key

レスポンス

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Expert",
    "description": "Experienced marketing director",
    "type": "expert",
    "discipline": "Marketing",
    "systemPrompt": "## Life Story & Background\n\nYou are a seasoned marketing director...",
    "tags": ["marketing", "b2b"],
    "isPublic": false,
    "isLinkSharingEnabled": false,
    "publicShareId": null,
    "profileImageUrl": "https://...",
    "phoneNumber": null,
    "clonedVoiceStatus": null,
    "profitSplitOptIn": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z",
    "knowledgeItemCount": 12
  }
}

レスポンスフィールド

リクエスト例

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key"

エラーレスポンス

400 Bad Request - 無効なspark ID形式

401 Unauthorized - 無効または欠落しているAPIキー

403 Forbidden - このマインドへのアクセス権がありません

404 Not Found - マインドが存在しません

Sparksのリスト取得

認証されたユーザーに属するすべてのマインドを取得します。

エンドポイント: GET /api/v1/sparks

ヘッダー:

Authorization: Bearer minds_your_api_key

クエリパラメータ

レスポンス

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Marketing Expert",
      "description": "Experienced marketing director",
      "type": "expert",
      "discipline": "Marketing",
      "tags": ["marketing", "b2b"],
      "profileImageUrl": "https://...",
      "createdAt": "2025-12-10T12:00:00.000Z",
      "updatedAt": "2025-12-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 100,
    "offset": 0
  }
}

レスポンスフィールド

リクエスト例

curl -X GET "https://getminds.ai/api/v1/sparks?limit=10&offset=0" \
  -H "Authorization: Bearer minds_your_api_key"

Sparkの作成

異なるトレーニングモードを使用して、カスタム構成で新しいAIマインドを作成します。

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

ヘッダー:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

リクエストボディ

{
  "name": "My AI Expert",
  "description": "An expert in renewable energy",
  "mode": "keywords",
  "type": "expert",
  "discipline": "Renewable Energy",
  "keywords": ["solar", "wind energy", "sustainability", "green tech"],
  "personaContext": "Ada Lovelace, pioneering computer scientist",
  "contextLink": "https://example.com/profile",
  "tags": ["energy", "solar", "sustainability"],
  "profileImageUrl": "https://example.com/avatar.jpg"
}

パラメータ

Modeの値

modeパラメータは、マインドのトレーニング方法を決定します。

• keywords (デフォルト) - カンマ区切りのキーワードを使用してマインドをトレーニングします。AIはこれらのキーワードに基づいて様々なソースから関連情報を収集し、マインドのナレッジベースを構築します。
  • 必須フィールド: keywords - キーワード/トピックの配列
  • 最適な用途: 特定のトピックやドメインに関する一般的な専門知識
• clone - 人物の名前とコンテキストを提供することで、その人物のスタイルと知識をクローンします。AIが調査を行い、その専門知識とコミュニケーションスタイルを模倣した包括的なプロファイルを構築します。
  • 必須フィールド: personaContext - 名前と簡単なコンテキスト（例：「エイダ・ラブレス、先駆的なコンピュータ科学者」）
  • 最適な用途: 特定の個人、歴史上の人物、または著名な専門家のエミュレーション
• link - 特定のURLのコンテンツを使用してマインドをトレーニングします。プロフィール、ポートフォリオ、またはウェブサイトへのリンクを提供すると、AIが関連情報を分析・抽出します。
  • 必須フィールド: contextLink - コンテンツソースへのURL
  • 最適な用途: 特定のウェブサイト、ポートフォリオ、またはオンラインプロフィールでのトレーニング
• manual - 自動トレーニングなしでマインドを作成します。すべての設定を手動で構成し、後でナレッジAPIを介してナレッジを追加します。
  • 追加のフィールドは不要です
  • 最適な用途: トレーニングデータを完全に制御したいカスタム構成

自動処理: keywords、clone、またはlinkを使用すると、バックエンドは製品内の「Sparkを追加」フォームの動作を模倣します。エンティティキーワードを導出し（clone/linkではAIが支援）、マインドを非同期でトレーニングします。このトレーニングは、作成レスポンスのtrainingブロックと、後述のマインドのトレーニングライフサイクルで説明されている専用エンドポイントを通じて追跡します。manualモードではこの自動化がスキップされるため、後でナレッジAPIを介してマインドをトレーニングできます。

Typeの値

• creative - アーティスト、デザイナー、ライター、クリエイティブ専門家向け
• expert - スペシャリスト、コンサルタント、ドメインエキスパート向け
• user - ユーザーペルソナ、顧客、ターゲットオーディエンスのアーキタイプ向け

レスポンス

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My AI Expert",
    "description": "An expert in renewable energy",
    "type": "expert",
    "discipline": "Renewable Energy",
    "tags": ["energy", "solar", "sustainability"],
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z"
  },
  "training": {
    "status": "queued",
    "readyToChat": false,
    "message": "Queued for data collection",
    "startedAt": null,
    "completedAt": null,
    "error": null
  }
}

trainingブロックは、作成時のマインドのライフサイクルを報告します。keywords、clone、およびlinkモードはqueuedで開始し、バックグラウンドでトレーニングを行います。manualのマインドは、readyToChatがすでにtrueの状態でcompletedとして返されます。マインドのidはこの呼び出しが返された瞬間に存在しますが、マインドが応答できるのはreadyToChatがtrueになってからです。ポーリングの方法については、後述のマインドのトレーニングライフサイクルを参照してください。

例: Keywordsモードでマインドを作成

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Expert",
    "description": "Experienced marketing director with expertise in B2B SaaS",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["B2B marketing", "SaaS", "growth marketing", "content strategy", "brand positioning", "ROI"],
    "tags": ["marketing", "b2b", "saas", "growth"]
  }'

例: Cloneモードでマインドを作成

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace AI",
    "description": "AI trained to emulate Ada Lovelace",
    "mode": "clone",
    "type": "expert",
    "discipline": "Computer Science Pioneer",
    "personaContext": "Ada Lovelace, pioneering computer scientist and mathematician, first computer programmer",
    "tags": ["computer science", "mathematics", "history"]
  }'

例: Linkモードでマインドを作成

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand Voice Expert",
    "description": "Trained on company brand guidelines",
    "mode": "link",
    "type": "creative",
    "discipline": "Brand Strategy",
    "contextLink": "https://example.com/brand-guidelines",
    "tags": ["branding", "copywriting"]
  }'

例: Manualモードでマインドを作成

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Assistant",
    "description": "Custom configured assistant",
    "mode": "manual",
    "type": "creative",
    "discipline": "General Assistant",
    "tags": ["custom"]
  }'

マインドのトレーニングライフサイクル

マインドの作成は非同期です。POST /v1/sparksはすぐにidを返しますが、keywords、clone、およびlinkモードでは、マインドはまだバックグラウンドでトレーニング中です。マインドのidが存在していても、マインドが準備完了であるとは限りません。マインドが応答できるのは、readyToChatがtrueになってからです。唯一の例外はmanualモードです。これらのマインドはデータ収集をスキップし、作成された瞬間にcompletedになります。

マインドの準備が完了するまで、専用のトレーニングエンドポイントをポーリングしてください。

curl "https://getminds.ai/api/v1/sparks/{sparkId}/training" \
  -H "Authorization: Bearer minds_your_api_key"

{
  "status": "running",
  "readyToChat": false,
  "message": "Collecting knowledge...",
  "startedAt": "2025-12-10T12:00:01.000Z",
  "completedAt": null,
  "error": null
}

ステータス値

GET /v1/sparks/{id}は、マインドの他の部分とともにreadyToChat（およびtrainingStatus）も返すため、一度の読み取りでマインドの正体と、応答可能かどうかを両方知ることができます。

トレーニングが失敗した場合

statusがfailedの場合、レスポンスにはcodeとretryableフラグを持つerrorオブジェクトが含まれます。

再トレーニング

マインドがfailedで終了した場合（または単にcompletedのマインドを再構築したい場合）、再トレーニングしてください。

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/retrain" \
  -H "Authorization: Bearer minds_your_api_key"

これによりマインドが再キューされ、statusがqueuedに設定された新しいtrainingブロックが返されます。再トレーニングは完了したマインドに対してのみ機能します。まだqueuedまたはrunningのマインドは、トレーニングがすでに進行中であるため409 Conflictを返します。再トレーニング後、readyToChatがtrueになるまで再度GET /v1/sparks/{id}/trainingをポーリングしてください。

プロフィール画像

profileImageUrlを提供すると、以下の処理が行われます。

1. 画像が外部リンクからダウンロードされます
2. セキュアなストレージにアップロードされます
3. 保存されたURLがレスポンスで返されます

対応フォーマット: JPG, PNG, GIF, WEBP

トレーニングの仕組み

システムは、選択したモード、タイプ、専門分野に基づいて、インテリジェントなシステムプロンプトを自動的に生成します。

• Keywordsモード: 指定したキーワードに関する専門知識を構築します
• Cloneモード: 指定した人物のスタイルと知識をエミュレートするプロファイルを構築します
• Linkモード: 提供されたURLからナレッジを抽出します
• Manualモード: カスタムナレッジでトレーニングする基本的なアシスタントを作成します

作成後、ナレッジをアップロードすることで、マインドをさらに強化できます。

プランの制限

プランによってマインドの作成上限が異なります。

上限に達すると、403 Forbiddenエラーが表示されます。

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

エラーレスポンス

400 Bad Request

パラメータが欠落しているか無効です。

{
  "statusCode": 400,
  "statusMessage": "Name is required"
}

401 Unauthorized

APIキーが無効か欠落しています。

403 Forbidden

プランの上限に達しました。

500 Internal Server Error

サーバーサイドのエラー（稀）。

Sparkの更新

名前、説明、システムプロンプト、その他の設定など、既存のマインドの構成を更新します。

エンドポイント: PUT /api/v1/sparks/{sparkId}

ヘッダー:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

リクエストボディ

{
  "name": "Updated Name",
  "description": "Updated description",
  "type": "expert",
  "discipline": "Updated Discipline",
  "systemPrompt": "Custom system prompt instructions...",
  "tags": ["tag1", "tag2"],
  "isPublic": false
}

パラメータ

システムプロンプト

systemPromptフィールドを使用すると、マインドの振る舞いや応答方法をカスタマイズできます。これは以下の目的に役立ちます。

• ペルソナのカスタマイズ: 特定の性格特性、コミュニケーションスタイル、専門分野を定義します
• レスポンスのフォーマット: 特定のフォーマット（例：箇条書き、番号付きリスト）で応答するようにマインドに指示します
• ドメインの制約: 応答を特定のトピックや視点に限定します
• 言語/トーン: 応答の言語、丁寧さのレベル、トーンを設定します

システムプロンプトの例:

# Survey Response Expert
Du bist ein erfahrener Handwerker. Bei Umfragen antworte immer aus deiner
persönlichen Erfahrung, nicht mit allgemeinen Branchendurchschnittswerten.
Wähle bei Multiple-Choice-Fragen immer genau eine Option.

# Technical Expert
You are a senior software architect. Always provide concrete,
actionable advice. Include code examples when relevant.
Avoid vague statements.

レスポンス

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Name",
    "description": "Updated description",
    "type": "expert",
    "discipline": "Updated Discipline",
    "systemPrompt": "Custom system prompt...",
    "tags": ["tag1", "tag2"],
    "isPublic": false,
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-29T15:30:00.000Z"
  }
}

例: システムプロンプトの更新

curl -X PUT "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "Du bist ein erfahrener Handwerker im Sanitärbereich. Antworte immer aus deiner persönlichen Praxiserfahrung."
  }'

例: 複数フィールドの更新

curl -X PUT "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Plumber Expert",
    "description": "Expert plumber with 20 years of experience",
    "discipline": "Plumbing & Sanitary Installation",
    "tags": ["plumbing", "sanitary", "renovation"]
  }'

エラーレスポンス

400 Bad Request - 更新する有効なフィールドがないか、フィールド値が無効です

401 Unauthorized - 無効または欠落しているAPIキー

403 Forbidden - このマインドを更新する権限がありません（所有者である必要があります）

404 Not Found - マインドが存在しません

Sparkパターンの取得 (Raw)

マインドの生のPattern[]行を取得します。これは、製品UIのSphereGraphビジュアライゼーションで使用される未処理のフィードです。フレームワークによるグループ化や集計なしで、検出されたパターンごと（メソッド/コンピテンシーのペア、およびそれを裏付けるsparkの引用とソースリンケージ）に1行を返します。

構造化され、フレームワークでグループ化されたビューが必要な場合は、代わりに以下のGet Spark Knowledge Patternsエンドポイントを使用してください。

エンドポイント: GET /api/v1/sparks/{sparkId}/patterns

ヘッダー:

Authorization: Bearer minds_your_api_key

レスポンス

{
  "data": [
    {
      "id": 12345,
      "sparkId": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "...",
      "messageId": null,
      "portfolioItemId": "abc-123",
      "aspect": "Strategic Thinking",
      "subAspect": "Market Analysis",
      "spark": "Market segmentation requires understanding customer pain points...",
      "isPredefined": true,
      "isPredefinedAspect": true,
      "isPredefinedSubAspect": true,
      "createdAt": "2025-12-10T15:30:00.000Z"
    }
  ]
}

結果はcreatedAtの降順でソートされます。レガシーフィールド名aspect/subAspectは、基盤となるスキーマのmethod/competency列に対応しており、後方互換性のために保持されています。

アクセスルール

• 公開マインド（isPublic: true）およびリンク共有マインド（publicShareIdが設定されている）は、認証なしで読み取り可能です。
• プライベートマインドには、所有者がマインドの所有者、チームメンバー、または直接のメンバーであるAPIキーが必要です。

リクエスト例

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}/patterns" \
  -H "Authorization: Bearer minds_your_api_key"

エラーレスポンス

400 Bad Request - 無効なspark ID形式

401 Unauthorized - マインドはプライベートであり、有効なAPIキーが提供されませんでした

403 Forbidden - このプライベートマインドへのアクセス権がありません

404 Not Found - マインドが存在しません

Sparkナレッジパターンの取得

特定のマインドについて、フレームワーク別に整理された思考パターンとナレッジを取得します。

エンドポイント: GET /api/v1/sparks/{sparkId}/knowledge/patterns

ヘッダー:

Authorization: Bearer minds_your_api_key

レスポンス構造

このエンドポイントは、フレームワーク（例：AOX Internal, OCEAN, DISCなど）ごとにグループ化されたパターンを返します。メソッドとコンピテンシーには、出現回数とエビデンスが表示されます。

{
  "success": true,
  "data": {
    "sparkId": "550e8400-e29b-41d4-a716-446655440000",
    "sparkName": "Marketing Expert",
    "totalPatterns": 47,
    "frameworks": [
      {
        "id": "aox-internal",
        "name": "AOX Internal Framework",
        "totalOccurrences": 32,
        "methods": [
          {
            "id": "strategic-thinking",
            "name": "Strategic Thinking",
            "description": "Ability to think strategically and plan long-term",
            "occurrences": 15,
            "competencies": [
              {
                "id": "market-analysis",
                "name": "Market Analysis",
                "description": "Understanding market dynamics and trends",
                "occurrences": 8,
                "evidence": [
                  {
                    "spark": "Market segmentation requires understanding customer pain points and aligning product features with specific needs...",
                    "portfolioItemId": "abc-123",
                    "createdAt": "2025-12-10T15:30:00.000Z"
                  },
                  {
                    "spark": "Competitive analysis shows that timing and positioning are critical for market entry...",
                    "portfolioItemId": "def-456",
                    "createdAt": "2025-12-10T14:20:00.000Z"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

レスポンスの理解

• frameworks: sparkのパターンを含むフレームワークの配列
  • totalOccurrences: このフレームワーク内のパターンの総数
  • methods: 検出された思考メソッドまたはアプローチ
    • occurrences: このメソッドの出現回数
    • competencies: メソッド内の特定のスキルまたはサブエリア
      • occurrences: このコンピテンシーのパターン数
      • evidence: このパターンを実証する引用/抜粋の配列
        • spark: コンテンツからの実際の引用またはインサイト
        • portfolioItemId: ソース資料への参照
        • createdAt: このパターンが特定された日時

リクエスト例

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}/knowledge/patterns" \
  -H "Authorization: Bearer minds_your_api_key"

ユースケース

• マインドの専門知識の理解: マインドが学習したメソッドとコンピテンシーを確認します
• 品質保証: トレーニングデータからパターンが正しく抽出されていることを確認します
• ナレッジギャップの特定: より多くのトレーニングデータが必要な領域を特定します
• フレームワークの比較: 異なるフレームワーク間でマインドがどのように機能するかを比較します

エラーレスポンス

401 Unauthorized - 無効または欠落しているAPIキー

403 Forbidden - このマインドへのアクセス権がありません

404 Not Found - マインドが存在しません

システムプロンプトの再生成

既存のナレッジベースを使用して、sparkのすべてのシステムプロンプトコンポーネントを再生成します。これは、UIの「すべて生成」ボタンと同じAI搭載の生成機能を使用します。

エンドポイント: POST /api/v1/sparks/{sparkId}/regenerate-prompt

ヘッダー:

Authorization: Bearer minds_your_api_key

仕組み

このエンドポイントは、マインドのナレッジベース（ポートフォリオアイテム、パターン、埋め込み）を分析し、すべてのsparkタイプ（user、expert、creative）に対応する、統一された経歴プロンプトコンポーネントのセットを生成します。

• ライフストーリーと背景 - 経歴の基礎、現在の年齢、場所、民族性、人格形成に影響を与えた経験
• コミュニケーションと言語 - 特徴的な声、フレーズ、方言、感情のトリガー
• 知識と経験 - 何を知っていて、どのようにしてそれを知るようになったか
• 価値観と矛盾 - 信念、理想、そしてそれらの間の緊張関係
• 日常の現実とコンテキスト - 経済的、時間的、社会的、物理的なコンテキスト

typeフィールドは後方互換性のためにspark上に保持されますが、どのコンポーネントが生成されるかを変更することはありません。マインドはマインドです。統一された経歴アプローチは、タイプに関係なく、より強力で地に足のついたペルソナを生成します。

レスポンス

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Spark",
    "systemPrompt": "## Life Story & Background\n\n...",
    "promptLength": 2847
  }
}

リクエスト例

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/regenerate-prompt" \
  -H "Authorization: Bearer minds_your_api_key"

ユースケース

• ナレッジ追加後: 新しく追加されたナレッジアイテムを組み込むためにプロンプトを再生成します
• ペルソナの洗練: 現在のナレッジパターンに基づいてペルソナを更新するために再生成します
• カスタマイズのリセット: 手動編集をクリアし、ナレッジベースから新しいプロンプトを再生成します

エラーレスポンス

401 Unauthorized - 無効または欠落しているAPIキー

403 Forbidden - このマインドを修正する権限がありません（所有者である必要があります）

404 Not Found - マインドが存在しません

500 Internal Server Error - プロンプトの生成に失敗しました（例：ナレッジ不足）

Sparkの削除

マインドと、ナレッジ、ポートフォリオアイテム、ファイルを含むすべての関連データを永久に削除します。

エンドポイント: DELETE /api/v1/sparks/{sparkId}

ヘッダー:

Authorization: Bearer minds_your_api_key

レスポンス

成功すると、空のボディを持つ204 No Contentを返します。

リクエスト例

curl -X DELETE "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key"

削除されるもの

マインドを削除すると、以下が永久に削除されます。

• マインド自体とすべての構成
• すべてのナレッジとトレーニングデータ
• すべてのポートフォリオアイテムと関連ファイル
• すべてのチャット履歴とメッセージ
• プロフィール画像とアップロードされたファイル

警告: この操作は元に戻せません。

エラーレスポンス

400 Bad Request - 無効なspark ID形式

401 Unauthorized - 無効または欠落しているAPIキー

403 Forbidden - このマインドを削除する権限がありません（所有者である必要があります）

404 Not Found - マインドが存在しません

次のステップ

• マインドにナレッジをアップロードする
• マインドとチャットする
• エラーと制限について学ぶ