# 개요와 키

Lockpick API는 CLI와 AI 도우미가 사용하는 API입니다. 같은 키, 권한, 한도를 그대로 씁니다.

Lockpick API는 Lockpick 주소의 `/api/cli/v1`에 있습니다. CLI와 MCP 서버가 모두 이 API를 사용합니다. 일부 도구는 클라이언트에서 API 읽기를 조합합니다. 기다리기는 스캔을 반복해서 확인하고, 평가는 완료 시각, 검사 범위, 열린 문제에 정책을 적용합니다. 이 기능의 HTTP 작업은 [참고 문서](/ko/docs/api/reference)에서 볼 수 있습니다.

## 키

모든 요청은 베어러 토큰으로 키를 함께 보냅니다.

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

키는 CLI `lockpick login`으로 로그인해서 받습니다. 이때 브라우저에서 승인하라는 안내가 나옵니다. 키는 `lpk_`로 시작하고, 승인한 [권한](/ko/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`입니다. 알려진 재시도 시간은 `Retry-After` HTTP 헤더에도 나타납니다. `webUrl`은 다음 단계로 가는 링크이며, 없으면 `null`입니다. `requestId`로 지원팀이 작업 실패를 추적할 수 있습니다. MCP 도구는 이 필드들을 자신의 오류 객체 형식으로 정규화하며, 이때 `agentCode`는 `code`라는 이름이 됩니다.

| HTTP 상태 | 의미                                                   |
| ------- | ---------------------------------------------------- |
| 400     | 잘못된 입력이거나 지원하지 않는 버전입니다                              |
| 401     | 자격 증명이 없거나, 만료되었거나, 폐기되었습니다                          |
| 402     | 요금제, 사이트 한도 또는 스캔 허용량 때문에 작업할 수 없습니다                 |
| 403     | 자격 증명의 범위 또는 프로젝트 접근 권한이 작업을 허용하지 않습니다               |
| 404     | 리소스 또는 기능을 사용할 수 없습니다                                |
| 409     | 충돌이 있거나, 증명 또는 승인이 없거나 만료되었거나, 취소되었거나, 재검사를 쓸 수 없습니다 |
| 422     | 출력이 지원하는 크기를 넘었습니다                                   |
| 429     | 요청 한도에 도달했습니다                                        |
| 500     | 내부 오류입니다                                             |
| 503     | 스캔 용량을 사용할 수 없습니다                                    |

> **Good to know**
>
> API는 베타 버전입니다. [참고 문서](/ko/docs/api/reference)에는 모든 작업이 입력, 응답, 필요한 권한과 함께 나열되어 있으며, [openapi.json](/openapi.json)에서는 OpenAPI 3.1 형식으로 설명합니다.