# Visão geral e chaves

A API do Lockpick é o que a CLI e os assistentes usam, com as mesmas chaves, permissões e limites.

A API do Lockpick fica em `/api/cli/v1`, no seu endereço do Lockpick. A CLI e o servidor MCP usam ambos a API. Algumas ferramentas compõem leituras da API no cliente: esperar faz consultas a uma verificação, e a avaliação aplica uma política à hora de conclusão, à cobertura e aos achados abertos. Veja a [referência](/pt-BR/docs/api/reference) para as operações HTTP por trás delas.

## Chaves

Toda requisição carrega uma chave como token bearer.

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

Você obtém uma chave fazendo login com a CLI, `lockpick login`, que pede que você a aprove no seu navegador. As chaves começam com `lpk_`, carregam as [permissões](/pt-BR/docs/mcp/permissions) que você aprovou e expiram quando não são usadas. Gerencie-as no Lockpick, em **Adicionar à sua IA**, na aba **CLI e chaves**.

## Respostas

Toda resposta é JSON, no mesmo formato, com `data` preenchido quando funcionou e `error` preenchido quando não funcionou.

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

Chamadas HTTP com falha retornam `data: null`, uma string `error` legível e um `errorCode`. As falhas de operação também incluem `details` com o erro estruturado do agente; recusas antecipadas de autenticação ou de recurso podem omiti-lo.

```json title="Erro da operação"
{
  "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` é um número de segundos, ou `null` quando nenhum tempo de nova tentativa é conhecido. Um tempo de nova tentativa conhecido também aparece no cabeçalho HTTP `Retry-After`. `webUrl` é um link para o próximo passo, ou `null`; `requestId` permite que o suporte rastreie uma falha de operação. As ferramentas MCP normalizam esses campos no objeto de erro delas, onde `agentCode` se chama `code`.

| Status HTTP | Significado                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------- |
| 400         | Entrada inválida ou versão não suportada                                                        |
| 401         | Credencial ausente, expirada ou revogada                                                        |
| 402         | Plano, limite de sites ou cota de verificações impede a operação                                |
| 403         | O escopo da credencial ou o acesso ao projeto não permite a operação                            |
| 404         | Recurso ou funcionalidade indisponível                                                          |
| 409         | Conflito, prova ou aprovação ausente ou expirada, cancelamento ou nova verificação indisponível |
| 422         | A saída excede o tamanho suportado                                                              |
| 429         | Limite de requisições atingido                                                                  |
| 500         | Erro interno                                                                                    |
| 503         | Capacidade de verificação indisponível                                                          |

> **Good to know**
>
> A API está em beta. A [referência](/pt-BR/docs/api/reference) lista cada operação
> com as suas entradas, a sua resposta e a permissão que ela exige, e o
> [openapi.json](/openapi.json) a descreve em OpenAPI 3.1.