> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindfort.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MindFort API の概要

> MindFort API に認証し、承認済みターゲット、認証情報、カバレッジチェック、アセスメント、検出結果、分析、レポートを管理します。

## ベース URL

すべての API リクエストは次の URL に送信します。

```text theme={null}
https://api.mindfort.app
```

## 認証

MindFort API は **Bearer トークン**認証を使用します。すべてのリクエストの `Authorization` ヘッダーに MindFort API キーを含めてください。

```bash theme={null}
Authorization: Bearer <your-api-key>
```

API キーは、[MindFort Dashboard](https://cloud.mindfort.app) の **Settings > API Keys** で生成できます。

## レート制限

* **クライアントごとの制限:** 1 分あたり 60 リクエスト
* **全体の制限:** 1 分あたり 100 リクエスト

レート制限に達すると、レスポンスに `Retry-After: 60` ヘッダーが含まれます。API はエラーメッセージとともに HTTP `429` を返します。

## API の対象範囲

公開 REST API は、承認された組織単位の製品機能を公開しています。

* ターゲットの一覧表示、取得、作成、更新、確認付きの削除
* テスト用認証情報の作成、ローテーション、メタデータの確認、削除
* カバレッジチェックと集計されたカバレッジの参照
* 有効な場合の候補ターゲットの検出と Discovery の提案の管理
* アセスメントの実行、一覧表示、確認、キャンセル
* 検出結果の一覧表示と取得、ライフサイクルステータスの更新、重大度の上書き、再テスト
* 検出結果のコメント管理と、パッチのサマリーおよび件数の確認
* 検出結果の分析、セキュリティメトリクス、経過日数、修正状況、SLA、ヘルススコアの参照
* レポートの作成、一覧表示、ポーリング、ダウンロード

リクエストとレスポンスのスキーマ、クエリパラメータ、例については、エンドポイントリファレンスを参照してください。

> [!NOTE]
>
> API では、ターゲットの検証操作、請求管理、API キー管理、組織メンバーシップ、ロール管理は公開していません。これらのワークフローは [MindFort Dashboard](https://cloud.mindfort.app) で完了してください。

## REST と MCP

REST と MCP は、組織のスコープに関するルールと主要なリソースの仕様を共有していますが、利用可能な操作、認証、ページネーションは異なります。アセスメントスケジュールの管理は MCP で利用でき、公開 REST ルートはありません。

| インターフェース | 認証 | ページネーション | 最適な用途 |
| - | - | - | - |
| **REST API** | MindFort API キー | エンドポイントに応じてカーソルまたは `limit`/`offset` | CI/CD、サービス、スクリプト、決定的な連携 |
| **MCP Server** | ブラウザベースの OAuth | 一覧ツールでの不透明な `cursor` 値 | MindFort のコンテキストを使用する対話型 AI エージェント |

MCP カタログは明示的に定義されており、選択した組織で利用できない機能ゲートされたツールやスキーマのバリアントは含まれない場合があります。[MCP ガイド](https://docs.mindfort.ai/ja/guides/mcp.md)を参照してください。

## ターゲットと認証情報のルール

ターゲットは認証された組織にスコープされます。

* `web_app` および `api` ターゲットには、HTTP(S) の `web_domain` が必要です。
* `network` ターゲットには、`ip_address` と組織機能 `network-targets` が必要です。
* REST または MCP で作成されたターゲットは未検証の状態で開始されます。アクティブなテストを開始する前に、ダッシュボードでドメインの所有権またはネットワークの検証を完了してください。
* `user:password@host` 形式の認証情報が埋め込まれたターゲット URL は拒否されます。

認証情報の一覧および詳細の読み取りではメタデータのみが返され、パスワード、API キーの値、TOTP シードは含まれません。専用のコード確認エンドポイントは一時的な認証コードやログイン URL を返すことができ、メールのプロビジョニングでは認証情報の作成に使用する保留中の受信箱 ID が返されます。

`api_key` 認証情報は `api` ターゲットでのみ有効です。追加する前に、検証用のルート、メソッド、リクエストの形式、キーの配置場所、想定される成功レスポンスを記述した、空でないターゲットレベルの `api_auth_instructions` を設定してください。

## カバレッジ

カバレッジは、アセスメント全体でテストされたセキュリティシナリオを示します。チェックの一覧には `GET /v1/coverage` を、集計件数には `GET /v1/coverage/overview` を使用します。どちらも任意で `target_id` によるフィルタリングが可能です。

現在の状態は `covered`、`failing`、`incomplete`、`in_progress`、`not_run` です。レスポンスには、シナリオの詳細、実行サマリー、関連する検出結果が含まれます。カバレッジは読み取り専用で、チェックと実行履歴はアセスメントによって維持されます。[カバレッジ](https://docs.mindfort.ai/ja/guides/coverage.md)を参照してください。

## Discovery

Discovery が有効な場合は、`/v1/discovery` を使用してステータスの確認、コンテキストとスケジュールの設定、実行の開始、候補ターゲットの承認または却下を行います。操作の一覧については、[ターゲットの検出](https://docs.mindfort.ai/ja/guides/discovery.md)を参照してください。

## ページネーション

REST の一覧エンドポイントでは、2 種類のページネーション方式を使用します。

* `GET /v1/assessments` はカーソルによるページネーションを使用します。次のカーソルが返されなくなるまで、返された `pagination.next_cursor` の値を次のリクエストの `cursor` パラメータとして渡してください。
* ターゲット、認証情報、カバレッジ、検出結果、コメント、パッチ、レポートのコレクションでは、各エンドポイントのスキーマに記載されたページネーションフィールドを使用します。オフセットベースのレスポンスには `total` が含まれ、カーソルベースのレスポンスでは次のページがある場合に `next_cursor` が返されます。

カーソルの値を作成したり変更したりしないでください。各カーソルは、同じフィルターとともに変更せずに渡してください。

## エラー形式

エラーは、一貫した公開 JSON 構造に従います。

```json theme={null}
{
  "error": "Human-readable error message",
  "code": "stable_error_code",
  "request_id": "abc123..."
}
```

`code` フィールドは、認識された対処可能な失敗の場合に含まれます。レスポンスには、安全なフィールド検証の詳細が含まれる場合もあります。サポートに問い合わせる際は、`request_id` を含めてください。

安定したエラーコードの例は次のとおりです。

* `target_not_verified`
* `api_auth_instructions_required`
* `assessment_already_running`
* `assessment_credits_insufficient`
* `assessment_queue_loading`
* `retest_already_running`

再試行可能なレスポンスには `Retry-After` が含まれる場合があります。HTTP `429 Too Many Requests` を受け取った場合は、そのヘッダーで指定された間隔だけ待ってから再試行し、リクエストの頻度を下げてください。組織を共有する連携間で、ポーリングを調整してください。

## コンポーネント ID

いくつかの API エンドポイントでは、ターゲット、検出結果、アセスメント、レポートなどのリソースの UUID が必要です。以下では、MindFort ダッシュボードで各 ID を確認できる場所を説明します。

### ターゲット

**Target Inventory** に移動し、ターゲットをクリックします。**Target ID** はターゲットの詳細ページに表示されます。

### 検出結果

`GET /v1/findings` を使用するか、ダッシュボードで検出結果を開きます。**Finding ID** は、詳細、コメント、ステータス、重大度、再テストのリクエストで特定の脆弱性を識別します。

一覧の結果は、`status`、`assessment_id`、`exclude_secured`、`target_id`、`severity` でフィルタリングできます。パラメータの詳細とダッシュボードとの対応については、[Findings API](https://docs.mindfort.ai/ja/api-reference/findings) を参照してください。

### アセスメント

**Assessments** を開いて実行を選択し、URL または詳細ビューから **Assessment ID** をコピーします。その実行の検出結果のみを一覧表示する場合は、これを `assessment_id` として使用します。

各ステージを追跡するには、アセスメントの詳細にある `stage_progress` を使用します。`NOT_STARTED` はステージの状態がまだ記録されていないことを、`RUNNING` または `ACTIVE` は処理が進行中であることを示し、その他の値は最終結果です。失敗した実行には、問題を説明する `failure_reason` が含まれる場合があります。

### 認証情報

ターゲットの認証情報を一覧表示して、認証情報 ID と安全なメタデータを取得します。認証情報 ID は、認証済みのアセスメントを実行する場合や、認証情報をローテーションまたは削除する場合に使用します。認証情報の一覧レスポンスにはメタデータのみが含まれます。

### レポート

`POST /v1/reports` でレポートを作成し、準備ができるまで `GET /v1/reports/{report_id}` をポーリングしてから、`GET /v1/reports/{report_id}/download` を呼び出して有効期限の短いダウンロード URL を取得します。

## Content Type

すべてのエンドポイントは `application/json` を受け付け、返します。JSON ボディを含むリクエストには、次のヘッダーを含める必要があります。

```http theme={null}
Content-Type: application/json
```

## プランとロールによるアクセス

API キーを使用しても、機能、請求、権限のチェックは回避されません。レポートと再テストには、アップグレードされたプランが必要です。Discovery とネットワークターゲットの機能には、対応する組織機能も必要です。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.