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

# API overview

> Activate agents from your own systems with a simple, predictable REST API

The Leme API lets your systems do what you already do in the dashboard: put an agent to work. You send an instruction, the agent runs with the same permissions, approvals, and tools it always has, and you collect the result — by polling or by webhook.

There are two ways to activate an agent from the outside:

<Columns cols={2}>
  <Card title="Runs API" icon="play" href="/api/runs">
    Full programmatic control: create a run per request, choose the instruction, follow the status, cancel, and receive completion webhooks.
  </Card>

  <Card title="Webhook trigger" icon="webhook" href="/triggers">
    A dedicated URL for external tools. The instruction is fixed on the trigger; every accepted event becomes a run.
  </Card>
</Columns>

Use the **Runs API** when your code decides what the agent should do on each call. Use a **webhook trigger** when the sender is an external tool (a form, Stripe, Zapier) and the instruction never changes.

## Authentication

Every API request is authenticated with an API token. Create one in the Leme dashboard under **Settings → API tokens**.

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

Tokens are scoped to a project and have a mode: `read_only` tokens can check statuses and list runs; creating or canceling runs requires a `read_write` token. The token is shown once at creation — store it in your secret manager.

<Warning>
  Treat the token like a password. Anyone holding it can act on your project within the token's mode. Revoke it in the dashboard if it leaks.
</Warning>

## Runs are asynchronous

Agent work takes seconds to minutes, so the API never blocks waiting for it. Creating a run returns `202 Accepted` immediately with a run resource you can follow:

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

Follow the run by polling `GET /api/v1/runs/:id`, or register a `callbackUrl` and let Leme notify you — see [Completion webhooks](/api/webhooks).

## Idempotency

Network calls fail and get retried. To make retries safe, send an `Idempotency-Key` header with every `POST`:

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

Repeating the same key with the same body returns the original response instead of creating a second run. The same key with a different body returns `409 idempotency_conflict`. Keys are remembered for 24 hours.

## Errors

Errors always use the same envelope, with a stable machine-readable `code`:

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

| HTTP | Common codes                                                |
| ---- | ----------------------------------------------------------- |
| 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`                  |

Handle errors by `code`, not by message — messages may change, codes will not.

## Rate limits

| Limit                     | Value          |
| ------------------------- | -------------- |
| Requests per token        | 120 per minute |
| Requests per organization | 600 per minute |
| Run creations per project | 30 per minute  |
| Active runs per project   | 20             |
| Request body              | 256 KiB        |

Requests over a limit return `429` with a `retry-after` header telling you how long to wait.

## OpenAPI

The full machine-readable specification is available at `GET https://app.leme.ai/api/openapi` — use it to generate clients or import the API into your tooling.