> ## 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.

# Visión general de la API

> Activa agentes desde tus sistemas con una API REST simple y predecible

La API de Leme permite que tus sistemas hagan lo que ya haces en el panel: poner a un agente a trabajar. Envías una instrucción, el agente la ejecuta con los mismos permisos, aprobaciones y herramientas de siempre, y recoges el resultado — consultando el estado o recibiendo un webhook.

Hay dos formas de activar un agente desde fuera:

<Columns cols={2}>
  <Card title="API de runs" icon="play" href="/es/api/runs">
    Control programático completo: crea un run por llamada, elige la instrucción, sigue el estado, cancela y recibe webhooks de finalización.
  </Card>

  <Card title="Trigger webhook" icon="webhook" href="/es/triggers">
    Una URL dedicada para herramientas externas. La instrucción es fija en el trigger; cada evento aceptado se convierte en un run.
  </Card>
</Columns>

Usa la **API de runs** cuando tu código decide qué debe hacer el agente en cada llamada. Usa un **trigger webhook** cuando quien envía es una herramienta externa (un formulario, Stripe, Zapier) y la instrucción nunca cambia.

## Autenticación

Cada solicitud se autentica con un token de API. Crea el tuyo en el panel de Leme, en **Settings → API tokens**.

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

Los tokens pertenecen a un proyecto y tienen un modo: los tokens `read_only` consultan estados y listan runs; crear o cancelar runs requiere un token `read_write`. El token se muestra una sola vez al crearlo — guárdalo en tu gestor de secretos.

<Warning>
  Trata el token como una contraseña. Quien lo tenga puede actuar en tu proyecto dentro del modo del token. Si se filtra, revócalo en el panel.
</Warning>

## Los runs son asíncronos

El trabajo de un agente tarda de segundos a minutos, así que la API nunca bloquea esperando. Crear un run devuelve `202 Accepted` de inmediato, con un recurso que puedes seguir:

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

Sigue el run consultando `GET /api/v1/runs/:id`, o registra un `callbackUrl` y deja que Leme te avise — mira [Webhooks de finalización](/es/api/webhooks).

## Idempotencia

Las llamadas de red fallan y se reintentan. Para que los reintentos sean seguros, envía un header `Idempotency-Key` en cada `POST`:

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

Repetir la misma clave con el mismo cuerpo devuelve la respuesta original en lugar de crear un segundo run. La misma clave con un cuerpo distinto devuelve `409 idempotency_conflict`. Las claves se recuerdan durante 24 horas.

## Errores

Los errores usan siempre el mismo envelope, con un `code` estable y legible por máquina:

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

| HTTP | Códigos comunes                                             |
| ---- | ----------------------------------------------------------- |
| 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`                  |

Maneja los errores por `code`, no por mensaje — los mensajes pueden cambiar, los códigos no.

## Límites de solicitudes

| Límite                         | Valor          |
| ------------------------------ | -------------- |
| Solicitudes por token          | 120 por minuto |
| Solicitudes por organización   | 600 por minuto |
| Creaciones de run por proyecto | 30 por minuto  |
| Runs activos por proyecto      | 20             |
| Cuerpo de la solicitud         | 256 KiB        |

Las solicitudes por encima de un límite devuelven `429` con un header `retry-after` que indica cuánto esperar.

## OpenAPI

La especificación completa, legible por máquina, está disponible en `GET https://app.leme.ai/api/openapi` — úsala para generar clientes o importar la API en tus herramientas.