# 概要とキー

Lockpick APIは、CLIやAIアシスタントが使うAPIです。同じキー、権限、上限が適用されます。

Lockpick APIは、お使いのLockpickのアドレスにある `/api/cli/v1` で動作します。CLIとMCPサーバーはどちらもこのAPIを使います。一部のツールは、クライアント側でAPIの読み取りを組み合わせます。待機ではスキャンの状態を確認し続け、評価ではそのスキャンの完了時刻、カバレッジ、未解決の検出事項にポリシーを当てはめます。これらの裏側にあるHTTPの操作は、[リファレンス](/ja/docs/api/reference)で確認できます。

## キー

すべてのリクエストは、キーをベアラートークンとして送ります。

```
curl -H "Authorization: Bearer $LOCKPICK_KEY" https://www.lockpick.app/api/cli/v1/agent/me
```

キーは、CLIで `lockpick login` を実行してサインインすると取得できます。ブラウザーで承認を求められます。キーは `lpk_` で始まり、承認した[権限](/ja/docs/mcp/permissions)を持ちます。使われないまま一定期間が過ぎると期限切れになります。キーは Lockpick の **AIに追加** から、**CLIとキー** タブで管理できます。

## 応答

すべての応答は同じ形のJSONです。成功すると `data` に値が入り、失敗すると `error` に値が入ります。

```json title="レスポンス"
{ "data": { "sites": [] }, "error": null }
```

HTTP呼び出しが失敗すると、`data` は `null` になります。人が読める `error` の文字列と `errorCode` も返ります。操作が失敗した場合は、構造化されたエージェント用のエラーを `details` に含みます。認証や機能の制限で早い段階で拒否された場合は、`details` が省略されることがあります。

```json title="操作のエラー"
{
  "data": null,
  "error": "The request limit was reached. Retry in 60 seconds.",
  "errorCode": "RATE_LIMITED",
  "details": {
    "agentCode": "RATE_LIMITED",
    "message": "The request limit was reached.",
    "nextStep": "Wait before trying again.",
    "retryAfterSeconds": 60,
    "webUrl": null,
    "requestId": "req_example"
  }
}
```

`retryAfterSeconds` は秒数です。再試行の時刻が分からない場合は `null` になります。再試行の時刻が分かっている場合は、HTTPヘッダーの `Retry-After` にも入ります。`webUrl` は次の手順へのリンクで、ない場合は `null` です。`requestId` は、操作の失敗をサポートが追跡するために使います。MCPツールは、これらの項目をエラーオブジェクトにまとめます。その際、`agentCode` は `code` という名前になります。

| HTTPステータス | 意味                                                   |
| --------- | ---------------------------------------------------- |
| 400       | 入力が正しくないか、対応していないバージョンです                             |
| 401       | 認証情報がないか、期限切れか、取り消されています                             |
| 402       | プラン、サイト数の上限、またはスキャンの利用枠により、操作できません                   |
| 403       | 認証情報のスコープ、またはプロジェクトへのアクセス権で、この操作は許可されていません           |
| 404       | リソースがないか、機能が利用できません                                  |
| 409       | 競合しています。証明や承認が見つからないか期限切れです。キャンセル済み、または再チェックを利用できません |
| 422       | 出力が対応しているサイズを超えています                                  |
| 429       | リクエストの上限に達しました                                       |
| 500       | 内部エラーです                                              |
| 503       | スキャンの処理能力が利用できません                                    |

> **Good to know**
>
> APIはベータ版です。[リファレンス](/ja/docs/api/reference)には、すべての操作について入力、応答、必要な権限が載っています。[openapi.json](/openapi.json) では、同じ内容をOpenAPI 3.1で説明しています。