> ## Documentation Index
> Fetch the complete documentation index at: https://factory-changelog-jun25.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 準備状況レポートAPI

> エージェント準備状況レポートへプログラムからアクセスするためのREST APIリファレンス。

準備状況レポートAPIは、組織のエージェント準備状況評価データへプログラムからアクセスする手段を提供します。

***

## 認証

すべてのリクエストには`Authorization`ヘッダーにFactory APIキーが必要です：

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

APIキーは[app.factory.ai/settings/api-keys](https://app.factory.ai/settings/api-keys)で生成してください。

***

## ベースURL

```
https://app.factory.ai
```

***

## エンドポイント

### 準備状況レポートの一覧取得

組織の準備状況レポートを取得します。

```
GET /api/organization/maturity-level-reports
```

#### クエリパラメータ

| パラメータ        | 型       | 必須  | 説明                        |
| :----------- | :------ | :-- | :------------------------ |
| `repoId`     | string  | いいえ | リポジトリIDでレポートをフィルタ         |
| `limit`      | integer | いいえ | 返すレポートの最大数（正の値である必要があります） |
| `startAfter` | string  | いいえ | ページネーションカーソル用のレポートID      |

#### レスポンス

```json theme={null}
{
  "reports": [
    {
      "reportId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": 1701792000000,
      "repoUrl": "https://github.com/org/repo",
      "apps": {
        "apps/web": {
          "description": "メインのNext.jsアプリケーション"
        },
        "apps/api": {
          "description": "バックエンドAPIサービス"
        }
      },
      "report": {
        "lint_config": {
          "numerator": 2,
          "denominator": 2,
          "rationale": "両方のアプリケーションでESLintが設定済み"
        },
        "type_check": {
          "numerator": 2,
          "denominator": 2,
          "rationale": "TypeScriptのstrictモードが有効"
        }
      },
      "commitHash": "abc123def456",
      "branch": "main",
      "hasLocalChanges": false,
      "hasNonRemoteCommits": false,
      "modelUsed": {
        "id": "claude-sonnet-4-5",
        "reasoningEffort": "high"
      },
      "droidVersion": "0.30.0"
    }
  ]
}
```

#### リクエスト例

```bash theme={null}
curl -X GET "https://app.factory.ai/api/organization/maturity-level-reports?limit=10" \
  -H "Authorization: Bearer fk-your-api-key"
```

***

## 準備状況レポートスキーマ

### レポートオブジェクト

| フィールド                 | 型        | 説明                         |
| :-------------------- | :------- | :------------------------- |
| `reportId`            | string   | レポートの一意識別子（UUID）           |
| `createdAt`           | number   | レポートが作成されたUnixタイムスタンプ（ミリ秒） |
| `repoUrl`             | string   | 評価されたリポジトリURL              |
| `apps`                | object   | アプリケーションパスから説明オブジェクトへのマップ  |
| `report`              | object   | 基準IDから評価結果へのマップ            |
| `commitHash`          | string?  | 評価時のGitコミットハッシュ            |
| `branch`              | string?  | 評価時のGitブランチ名               |
| `hasLocalChanges`     | boolean? | コミットされていない変更が存在したかどうか      |
| `hasNonRemoteCommits` | boolean? | プッシュされていないコミットが存在したかどうか    |
| `modelUsed`           | object?  | 評価に使用されたモデル設定              |
| `droidVersion`        | string?  | レポートを生成したCLIバージョン          |

### アプリ説明オブジェクト

| フィールド         | 型      | 説明                   |
| :------------ | :----- | :------------------- |
| `description` | string | アプリケーションの機能に関する簡潔な説明 |

### 基準評価オブジェクト

| フィールド         | 型      | 説明                                    |
| :------------ | :----- | :------------------------------------ |
| `numerator`   | number | 基準を満たしたサブアプリケーションの数（0からdenominatorまで） |
| `denominator` | number | 基準が評価されたサブアプリケーションの数（最低1）             |
| `rationale`   | string | 評価結果の説明                               |

### 使用モデルオブジェクト

| フィールド             | 型      | 説明                                   |
| :---------------- | :----- | :----------------------------------- |
| `id`              | string | モデル識別子                               |
| `reasoningEffort` | string | 推論労力レベル（`low`、`medium`、`high`、`off`） |

***

## ページネーション

大きな結果セットに対しては、カーソルベースのページネーションを使用してください：

1. 希望する`limit`で初回リクエストを実行
2. レスポンスの最後のアイテムの`reportId`を取得
3. そのIDを次のリクエストで`startAfter`として渡す

```bash theme={null}
# 最初のページ
curl "https://app.factory.ai/api/organization/maturity-level-reports?limit=10"

# 次のページ（前回レスポンスの最後のreportIdを使用）
curl "https://app.factory.ai/api/organization/maturity-level-reports?limit=10&startAfter=550e8400-e29b-41d4-a716-446655440000"
```

***

## 使用例

### CI/CD統合

各評価後にレポートを取得することで、時系列での準備状況スコアを追跡：

```bash theme={null}
# 特定リポジトリの最新レポートを取得
curl "https://app.factory.ai/api/organization/maturity-level-reports?repoId=123&limit=1" \
  -H "Authorization: Bearer $FACTORY_API_KEY"
```

### カスタムダッシュボード

すべてのレポートを取得し、集約メトリクスを計算することで内部ダッシュボードを構築：

```javascript theme={null}
const response = await fetch(
  "https://app.factory.ai/api/organization/maturity-level-reports",
  { headers: { Authorization: `Bearer ${apiKey}` } }
);
const { reports } = await response.json();

// 平均レベルを計算
const avgLevel =
  reports.reduce((sum, r) => sum + calculateLevel(r), 0) / reports.length;
```

### 自動アラート

準備状況スコアが閾値を下回った際のアラートを設定：

```bash theme={null}
# 最近のレポートを取得し、後退がないか確認
reports=$(curl -s "https://app.factory.ai/api/organization/maturity-level-reports?limit=50" \
  -H "Authorization: Bearer $FACTORY_API_KEY")

# 後退を処理し、アラートを送信...
```

***

## エラーレスポンス

| ステータス | 説明            |
| :---- | :------------ |
| `400` | 無効なリクエストパラメータ |
| `401` | APIキーが欠如または無効 |
| `500` | 内部サーバーエラー     |