> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leme.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral da API

> Ative agents a partir dos seus sistemas com uma API REST simples e previsível

A API da Leme permite que seus sistemas façam o que você já faz no dashboard: colocar um agent para trabalhar. Você envia uma instrução, o agent executa com as mesmas permissões, aprovações e ferramentas de sempre, e você coleta o resultado — consultando o status ou recebendo um webhook.

Existem duas formas de ativar um agent de fora:

<Columns cols={2}>
  <Card title="API de runs" icon="play" href="/pt-BR/api/runs">
    Controle programático completo: crie um run por chamada, escolha a instrução, acompanhe o status, cancele e receba webhooks de conclusão.
  </Card>

  <Card title="Trigger webhook" icon="webhook" href="/pt-BR/triggers">
    Uma URL dedicada para ferramentas externas. A instrução é fixa no trigger; cada evento aceito vira um run.
  </Card>
</Columns>

Use a **API de runs** quando o seu código decide o que o agent deve fazer a cada chamada. Use um **trigger webhook** quando quem envia é uma ferramenta externa (um formulário, Stripe, Zapier) e a instrução nunca muda.

## Autenticação

Toda requisição é autenticada com um token de API. Crie o seu no dashboard da Leme em **Settings → API tokens**.

```text theme={null}
Authorization: Bearer leme_pat_v1_...
```

Tokens pertencem a um projeto e têm um modo: tokens `read_only` consultam status e listam runs; criar ou cancelar runs exige um token `read_write`. O token é exibido uma única vez na criação — guarde-o no seu gerenciador de secrets.

<Warning>
  Trate o token como uma senha. Quem o possuir pode agir no seu projeto dentro do modo do token. Se vazar, revogue-o no dashboard.
</Warning>

## Runs são assíncronos

O trabalho de um agent leva de segundos a minutos, então a API nunca bloqueia esperando. Criar um run retorna `202 Accepted` imediatamente, com um recurso que você pode acompanhar:

```json theme={null}
{
  "id": "run_id",
  "object": "agent.run",
  "status": "queued",
  "urls": { "self": "/api/v1/runs/run_id" }
}
```

Acompanhe consultando `GET /api/v1/runs/:id`, ou registre um `callbackUrl` e deixe a Leme avisar você — veja [Webhooks de conclusão](/pt-BR/api/webhooks).

## Idempotência

Chamadas de rede falham e são repetidas. Para tornar retentativas seguras, envie um header `Idempotency-Key` em todo `POST`:

```text theme={null}
Idempotency-Key: pedido-4821
```

Repetir a mesma chave com o mesmo corpo devolve a resposta original em vez de criar um segundo run. A mesma chave com corpo diferente retorna `409 idempotency_conflict`. As chaves são lembradas por 24 horas.

## Erros

Erros usam sempre o mesmo envelope, com um `code` estável e legível por máquina:

```json theme={null}
{
  "error": {
    "code": "agent_not_found",
    "httpStatus": 404,
    "message": "Agent not found"
  }
}
```

| HTTP | Códigos comuns                                              |
| ---- | ----------------------------------------------------------- |
| 401  | `invalid_token`, `expired_token`, `token_revoked`           |
| 403  | `read_only_token`, `run_actor_not_allowed`                  |
| 404  | `agent_not_found`, `run_not_found`, `session_not_found`     |
| 409  | `idempotency_conflict`, `not_cancellable`, `session_closed` |
| 413  | `payload_too_large`                                         |
| 422  | `callback_url_invalid`                                      |
| 429  | `rate_limited`, `concurrent_runs_exceeded`                  |

Trate erros pelo `code`, não pela mensagem — mensagens podem mudar, códigos não.

## Limites de requisição

| Limite                      | Valor          |
| --------------------------- | -------------- |
| Requisições por token       | 120 por minuto |
| Requisições por organização | 600 por minuto |
| Criações de run por projeto | 30 por minuto  |
| Runs ativos por projeto     | 20             |
| Corpo da requisição         | 256 KiB        |

Requisições acima de um limite retornam `429` com um header `retry-after` indicando quanto esperar.

## OpenAPI

A especificação completa, legível por máquina, está disponível em `GET https://app.leme.ai/api/openapi` — use-a para gerar clients ou importar a API nas suas ferramentas.