# Overview and keys

The Lockpick API is what the CLI and assistants use, with the same keys, permissions and limits.

The Lockpick API lives at `/api/cli/v1` on your Lockpick address. The CLI and the MCP server both use it. Some tools compose API reads in the client: waiting polls a scan, and evaluation applies a policy to its completion time, coverage and open findings. See the [reference](/docs/api/reference) for the HTTP operations behind them.

## Keys

Every request carries a key as a bearer token.

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

You get a key by signing in with the CLI, `lockpick login`, which asks you to approve it in your browser. Keys start with `lpk_`, carry the [permissions](/docs/mcp/permissions) you approved and expire when unused. Manage them in Lockpick under **Add to your AI**, on the **CLI and keys** tab.

## Answers

Every response is JSON in the same shape, with `data` set when it worked and `error` set when it didn't.

```json title="Response"
{ "data": { "sites": [] }, "error": null }
```

Failed HTTP calls return `data: null`, a human-readable `error` string and an `errorCode`. Operation failures also include `details` with the structured agent error; early authentication or feature refusals may omit it.

```json title="Operation error"
{
  "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` is a number of seconds, or `null` when no retry time is known. A known retry time also appears in the `Retry-After` HTTP header. `webUrl` is a link to the next step or `null`; `requestId` lets support trace an operation failure. MCP tools normalize these fields into their error object, where `agentCode` is named `code`.

| HTTP status | Meaning                                                                          |
| ----------- | -------------------------------------------------------------------------------- |
| 400         | Invalid input or unsupported version                                             |
| 401         | Missing, expired or revoked credential                                           |
| 402         | Plan, site limit or scan allowance prevents the operation                        |
| 403         | Credential scope or project access does not allow the operation                  |
| 404         | Resource or feature unavailable                                                  |
| 409         | Conflict, missing/expired proof or approval, cancellation or unavailable recheck |
| 422         | Output exceeds the supported size                                                |
| 429         | Request limit reached                                                            |
| 500         | Internal error                                                                   |
| 503         | Scan capacity unavailable                                                        |

> **Good to know**
>
> The API is in beta. The [reference](/docs/api/reference) lists every
> operation with its inputs, answer and the permission it needs, and
> [openapi.json](/openapi.json) describes it in OpenAPI 3.1.