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

> ## Agent Instructions
> Notes on the Listo Partner Delivery API:
> - Every endpoint is under `https://api.listo.delivery/v1/` and authenticates with a bearer API key.
> - This documentation site is at https://docs.listo.delivery. The full machine-readable reference is the OpenAPI document at https://api.listo.delivery/docs/openapi.yaml (served by the API host, not by this site).
> - Any page of this site is also available as raw markdown by appending `.md` to its URL, for example https://docs.listo.delivery/en/guides/webhooks.md. The index of every page is https://docs.listo.delivery/llms.txt and all of them in one file is https://docs.listo.delivery/llms-full.txt.
> - Every page is published in English under https://docs.listo.delivery/en/ and in Spanish under https://docs.listo.delivery/es/, with the same path after the language. The API reference is under https://docs.listo.delivery/api-reference/ in English and https://docs.listo.delivery/es/api-reference/ in Spanish.
> - To debug an integration yourself: `GET /v1/request_logs` lists the calls your keys made with what you sent and what was answered, `GET /v1/events` lists the events Listo emitted, `GET /v1/webhook_deliveries` lists every attempt to deliver them, `POST /v1/events/{id}/resend` sends one event again and `POST /v1/test_webhooks` sends a sample event (`"test": true`). The page https://docs.listo.delivery/en/guides/debugging describes them. A resent event is a snapshot from when it happened; `GET /v1/deliveries` is still how you recover current state.
> - Every error response has `error.doc_url`, a page that explains that error code and what to do, and `error.request_id`, the same value as the `X-Request-Id` response header. All the pages are listed at https://docs.listo.delivery/en/errors. Filter `GET /v1/request_logs` with `request_id` to read the logged call.
> - A `409 account_exists` from `POST /v1/stores` means the restaurant already has its own Listo account: connect it instead of creating it, as the page https://docs.listo.delivery/en/guides/connect-existing-account describes.
> - Every live store carries one Plan Listo, charged to the partner. The exception is a connected restaurant that had already paid its current month: it keeps paying its own plan until its next renewal, shown as `paid_by: "store"` with the handover date in `pending_paid_by_on`. A `402 plan_required` from a quote, a delivery create or a retry means the store's plan is not paid or has ended; the page https://docs.listo.delivery/en/guides/plan-and-billing describes the plan, the `plan` block on a store and how to end or restart it.
> - An AI assistant (Claude Code, Cursor, Codex) can act through the same API key at `https://api.listo.delivery/mcp`, an MCP server over Streamable HTTP authenticated with `Authorization: Bearer <API key>`. Every tool runs the matching `/v1/` endpoint, and each one that moves money first previews and then needs a confirmation token; the page https://docs.listo.delivery/en/guides/connect-ai-client lists the tools and describes the two steps.

# Build with AI

> Point a coding agent at the right files, give it a key that cannot move money, and start from prompts that name the exact pages to read.

An AI coding agent integrates best when it reads the real documentation instead
of guessing from memory. This page lists the files an agent should be given, how
to hand it a key it cannot misuse, and a few prompts to copy that each name the
pages the agent has to read first.

## Files made for agents

Every address below is spelled in full: the root files are on `api.listo.delivery`, the documentation files are on `docs.listo.delivery`.

* **Root index**: `https://api.listo.delivery/llms.txt`. The first file an agent looks for. It only points at the files below.
* **Agent instructions**: `https://api.listo.delivery/AGENTS.md`. The short rules for an agent working on an integration, as markdown.
* **Documentation index**: `https://docs.listo.delivery/llms.txt`. Every guide and concept page with a one-line description.
* **All guides in one file**: `https://docs.listo.delivery/llms-full.txt`. One download with the full text of every guide, for an agent that cannot browse.
* **OpenAPI document**: `https://api.listo.delivery/docs/openapi.yaml`. The complete reference for `/v1/`, in the format code generators and agents read best.
* **Any page as markdown**: the page URL with `.md` added. For example `https://docs.listo.delivery/en/guides/webhooks.md`.

The generated reference pages have a markdown copy too, at the same address with
`.md` added, for example
`https://docs.listo.delivery/api-reference/deliveries/create-a-delivery.md`. For
the whole reference in one document, give the agent the OpenAPI document.

## Give an agent a read-only key

An agent that only has to read, list or debug should never hold a key that can
create or cancel anything. In the [partner dashboard](https://partners.listo.delivery),
issue the key with **Read-only key** ticked. A read-only key can call `GET` and
`HEAD` endpoints (balance, ledger, deliveries, request logs, events) and every
other call, including resending an event or sending a test webhook, answers
`403 read_only_key`.

A key is read-only or full access from the moment it is issued and never changes,
so to give an agent more power you issue another key and revoke the first.
Start with a **test key** in either case: it acts in test mode, where nothing real
happens. [Test mode](https://docs.listo.delivery/en/concepts/test-mode.md) explains what the simulated
courier does, and [Go live](https://docs.listo.delivery/en/guides/go-live.md) covers keys for production.

> [!WARNING]
>
> Keys are shown once. Put the key in an environment variable or a secret store the
> agent can read, never in the prompt, the repository or a chat.

## Errors point at their fix

Every error response carries two fields an agent can use without guessing:

* `doc_url`: the page that explains that exact `error.code`, what causes it and
  whether retrying can help. There is one page per code, all listed in the
  [error pages index](https://docs.listo.delivery/en/errors.md).
* `request_id`: the same value as the `X-Request-Id` header on the response. Quote it
  when you ask a person for help. `GET /v1/request_logs` lists the calls your keys
  made with what was sent and what was answered, and takes a `request_id` filter.

[Debugging your integration](https://docs.listo.delivery/en/guides/debugging.md) describes the request
logs, the events and the webhook deliveries an agent can read on its own.

## Connect an AI client over MCP

If your assistant is Claude, Cursor or Codex, you can connect it to Listo's MCP
server instead of having it write HTTP calls. [Connect Claude, Cursor or Codex](https://docs.listo.delivery/en/guides/connect-ai-client.md)
has the server address and the setup for each client. A read-only key works there
too: the assistant can read, and every tool that creates, changes or cancels
anything in your account is refused with `read_only_key`, because each tool runs
the matching `/v1/` endpoint. A tool that asks to confirm is refused at its
first step, so the assistant is never shown a preview it could not confirm.
Sending feedback to Listo (`submit_feedback`) still works.

## Prompts to copy

Each prompt names the pages to read. Paste it as it is, or add your own details
(your language, your framework, where the code lives). The agent should open the
pages before it writes anything.

### Integrate quote and create

```text theme={null}
Add Listo deliveries to this project using the Listo Partner Delivery API.

Read these first and follow them exactly:
- https://api.listo.delivery/AGENTS.md
- https://docs.listo.delivery/en/quickstart.md
- https://docs.listo.delivery/en/guides/quote-and-create.md
- https://api.listo.delivery/docs/openapi.yaml (the request and response shapes)

Use the test key in the LISTO_API_KEY environment variable. Build one function that
asks for a quote and one that creates a delivery from that quote, with the errors
handled by `error.code`. When a call fails, open the `doc_url` in the error body
before you retry. Do not invent fields that are not in the OpenAPI document.
```

### Verify webhook signatures

```text theme={null}
Add a webhook endpoint to this project that receives events from Listo.

Read these first:
- https://docs.listo.delivery/en/guides/webhooks.md
- https://docs.listo.delivery/en/concepts/signing.md

Verify the signature on the raw request body before parsing it, reject anything
older than the tolerance the page gives, answer 2xx first and do the work
afterwards, and ignore an event id you have already handled. Write tests that sign
a sample body with a test secret and check that a tampered body is rejected.
```

### Debug a failed call by its request id

```text theme={null}
A call to the Listo API failed. Its request id is <PASTE THE request_id HERE>.

Read these first:
- https://docs.listo.delivery/en/guides/debugging.md
- https://api.listo.delivery/AGENTS.md

Using the read-only key in LISTO_API_KEY, fetch that call from GET /v1/request_logs
(filter by request_id), read the status, the error code and the request body that
was sent, then open the `doc_url` of that error. Tell me what went wrong and what
to change in the code. Do not call any endpoint that writes.
```

### Reconcile my balance

```text theme={null}
Check that our books match the Listo balance.

Read these first:
- https://docs.listo.delivery/en/guides/balance-and-withdrawals.md
- https://docs.listo.delivery/en/concepts/money.md
- https://api.listo.delivery/docs/openapi.yaml (the balance and ledger operations)

Using the read-only key in LISTO_API_KEY, read GET /v1/balance and walk GET
/v1/ledger for the period I give you. Explain each kind of movement in the words
of the guide, list any movement you cannot match to a delivery, and report the
difference between the ledger total and the balance. Do not create or change
anything.
```

> [!NOTE]
>
> These prompts work in any agent that can fetch a URL or read a file. If yours
> cannot browse, download `llms-full.txt` and `openapi.yaml` once and put them in the
> project, then replace the URLs in the prompt with the file paths.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.