Lida via API
From your system's server, chat with Lida or ask her for a task. Lida replies with her rules and your context, which she treats as data. Every call is metered and paid from your account.
Chat with Lida
POST /lida/turns with an API key that has the Chat with Lida permission (create it in Settings → Development and send it in the Authorization: Bearer header). Each request is a turn: the person's message, the history, your instructions and your context. Lid doesn't store the conversation: you send the history with each request. Lid picks the model and the reply doesn't say which. Each turn is paid from your extra usage, within the key's monthly limit if you set one.
A turn's request
A JSON of up to 16 MB with images. Send Accept-Language: es or en for the error messages.
curl -X POST https://api.lid.pro/api/v1/lida/turns \
-H "Authorization: Bearer lpmcp_tu_llave_con_conversar" \
-H "Content-Type: application/json" \
-d '{
"message": "¿Cómo va el pedido 12?",
"instructions": "Respondes a los vendedores de FP, con frases cortas.",
"context": {
"cliente": "Comercial Ruiz",
"vendedor": "Ana"
},
"history": [],
"tools": [
{
"name": "buscar_pedido",
"description": "Busca un pedido por su número",
"parameters": {
"type": "object",
"properties": {
"numero": {
"type": "integer"
}
},
"required": [
"numero"
]
}
}
],
"locale": "es",
"timeZone": "America/Mexico_City"
}'| Field | What it is |
|---|---|
message | The person's message, up to 20 KB. Required, unless the request follows a tool call (the history ends with its results). |
history | The earlier conversation, up to 50 messages: the person's (role user, with text), Lida's (role assistant, with text or toolCalls) and your tools' results (role tool, with id, name and result). |
instructions | The tone and the task, up to 20 KB ("you answer FP's sales team"). They never override Lid's rules. |
context | Your system's data that Lida needs, as text or an object, up to 200 KB. Lida treats it as data. |
guides | Up to 10 guides of up to 16 KB, each with name (lowercase letters, numbers and dashes), when (when to use it, up to 160 characters) and text. Lida only reads the one the request needs. |
tools | Up to 20 of your system's tools, each with name, description and parameters (a JSON schema of type object, without pattern). |
images | Up to 5 images, each with mimeType (JPG, PNG, WebP or GIF) and base64 data, as in tasks. |
schema | Optional: a JSON schema for the reply, of type object and without pattern. If Lida doesn't follow it, the turn fails without charging. |
locale | es or en, the reply's language (es if you don't send it). |
timeZone | Your time zone (like America/Mexico_City), for today's date and time; without it, UTC. |
name | Optional: the name your assistant introduces itself with, up to 40 characters. |
stream | true for the streamed reply (also with Accept: text/event-stream). |
Your tools
When Lida wants to use one of your tools, the reply has type tool_calls with its name and the data it asks for. Lid never runs it or calls your system: you run it and send the result in the next request's history, and Lida goes on. There are up to 8 tool steps per turn; at the limit, Lida answers with what she has.
The streamed reply
With stream: true, the reply is text/event-stream: delta events (with text) while Lida writes, tool_calls (with toolCalls) if she wants a tool, done (with type, result, usage and turnId) at the end and error (with error) if something fails midway. An error before it starts comes back as JSON with its code. If you cut the connection midway, only what was used up to then is charged.
event: delta
data: {"text":"El pedido 12 "}
event: delta
data: {"text":"sale mañana."}
event: done
data: {"type":"text","usage":{"extraChargedCents":1,"extraLeftCents":1995,"fromPlan":false,"planPercentUsed":null,"monthCap":{"capCents":1000,"spentCents":375,"percentUsed":37.5}},"turnId":"…"}Your context is data, and who replies
Lid's rules go first: she never signs or moves money, never asks for payment details, passwords or codes, never shows a key and never makes up what you didn't give her. Then your instructions and your guides. The context, the history, your tools' results and the text in images are data: if they carry orders, Lida doesn't follow them. A full key anywhere in the request reaches her as "[llave]". Lida introduces herself as Lida, Lid's AI, unless you send name; if asked about the model, she says Lid picks the models she runs on. A turn doesn't change anything in Lid: MCP and the site's tools are for that.
A turn's reply
type says what it carries: text (Lida's text), json (result follows your schema) or tool_calls. usage has what came from your extra usage and what's left, in cents, and with a capped key, monthCap (capCents, spentCents and percentUsed: this month so far against the cap); turnId identifies the turn in your usage. A turn that fails because of Lid or the provider isn't charged.
{
"type": "tool_calls",
"toolCalls": [
{
"id": "call_1",
"name": "buscar_pedido",
"args": {
"numero": 12
}
}
],
"usage": {
"extraChargedCents": 1,
"extraLeftCents": 1996,
"fromPlan": false,
"planPercentUsed": null,
"monthCap": {
"capCents": 1000,
"spentCents": 374,
"percentUsed": 37.4
}
},
"turnId": "3f6c2a1e-7b2d-4c1a-9e8f-2a1b3c4d5e6f"
}A turn's errors
The five from tasks, with the same type and code, plus lida_from_browser. details.reason says why for lida_no_credits (balance or key_cap) and for lida_daily_limit (account_day, with resetsAt).
| Type | Status | Meaning |
|---|---|---|
lida_key_invalid | 401 | The key can't chat: it's missing, mistyped, expired or removed, it doesn't have the Chat with Lida permission or the account is blocked. The model isn't called and nothing is charged. |
lida_task_invalid | 400 | The request is outside a limit or a shape; details.field and details.reason say which. It isn't charged. |
lida_no_credits | 402 | Your account's balance isn't enough (balance, with details.buyUrl) or the key reached its monthly limit (key_cap). The model isn't called. |
lida_from_browser | 403 | The request came from a browser: the key only goes on your system's server. We let you know and the key keeps working from a server. |
lida_daily_limit | 429 | Your account reached its daily Lida via API limit (account_day); details.resetsAt says when it comes back. |
lida_unavailable | 503 | Lida couldn't reply or the 120 second limit passed. Nothing was charged: retry in a moment. |
The key only goes on your server
This key can't be used from a browser: it only goes on your system's server. POST /lida/turns doesn't answer browsers and a request with a browser's origin gets a 403 lida_from_browser without calling Lida; we let you know once a day per key. If the key was on a page, regenerate it in Lid.
Lida tasks
With an API key that has the Lida tasks permission, another system asks Lida to detect an order or extract its data with a JSON schema; the reply carries the result and what it cost.
The key
Create an API key with only the Lida tasks permission in Settings → Development and send it in the Authorization: Bearer header. That key works for tasks and nothing else, is shown only once and expires (30, 90 or 180 days; we email you before). Each task is paid from your account, never from a site's plan, and with dollar billing you can give the key a monthly cap. A site key can't run tasks.
An older Lida key (it starts with lida_) keeps working with the same body, reply and errors until you remove it.
The request
POST /lida/tasks with a JSON body. Send Accept-Language: es or en for the error messages.
curl -X POST https://api.lid.pro/api/v1/lida/tasks \
-H "Authorization: Bearer lpmcp_tu_llave_con_tareas" \
-H "Content-Type: application/json" \
-H "Accept-Language: es" \
-d '{
"task": "extract",
"system": "Extrae los datos del pedido del mensaje del cliente.",
"text": "Hola, quiero 500 tarjetas de presentación a dos caras para el viernes.",
"schema": {
"type": "object",
"properties": {
"producto": {
"type": "string"
},
"cantidad": {
"type": "integer"
},
"fechaEntrega": {
"type": "string"
}
},
"required": [
"producto",
"cantidad"
]
}
}'| Field | What it is |
|---|---|
task | detect (detect an order) or extract (extract its data). Required. |
system | The instructions for Lida, up to 50 KB. Required. |
context | Optional context, up to 100 KB. |
text | The text to check. Required if you send no images. |
images | Only with extract: up to 5 images, each with mimeType (JPG, PNG, WebP or GIF) and data in base64. |
schema | The exact shape of the reply: a JSON schema with type object, up to 100 KB and without pattern. Required. |
maxOutputTokens | Optional, from 256 to 16,384 (4,096 if you don't send it). |
The limits
- Up to 200 KB of text across system, context and text.
- Up to 5 images of 3.75 MB each and 12 MB in total.
- A schema with no regular expressions (pattern).
- A reply in under 80 seconds.
- Your account's daily task limit, with all your keys together. Tasks don't use the 60 requests per minute the key has on /agent/*.
The reply
result follows your schema. credits says what it cost and what the account has left while billing is in credits; with dollar billing, usage carries what was charged and what your extra usage has left, in cents. A failed task isn't charged, and Lid doesn't keep the text or the images.
{
"result": {
"producto": "Tarjetas de presentación a dos caras",
"cantidad": 500,
"fechaEntrega": "viernes"
},
"credits": {
"charged": 1,
"remaining": 249
},
"usage": {
"chargedCents": 3,
"extraLeftCents": 1997
}
}The errors
Five, each with its fixed type and code; the message comes in the Accept-Language language.
{
"error": {
"type": "lida_key_invalid",
"message": "La llave no sirve para Lida: falta, está mal escrita, venció, la quitaron o no tiene el permiso que este pedido necesita (Tareas de Lida o Conversar con Lida). Revísala en tu cuenta de Lid.",
"requestId": "req_9f2a1c"
}
}| Type | Status | Meaning |
|---|---|---|
lida_key_invalid | 401 | The key can't run tasks: it's missing, mistyped, expired or removed, lacks the Lida tasks permission, belongs to a site, or the account is blocked. The model isn't called and nothing is charged. |
lida_task_invalid | 400 | The task is outside the limits (the type, texts, images or schema); details.field says which. Nothing is charged. |
lida_no_credits | 402 | The account's balance isn't enough, or the key reached its monthly cap (details.reason key_cap). The task doesn't run. |
lida_daily_limit | 429 | The account reached its task limit for today; it works again tomorrow. |
lida_unavailable | 503 | Lida couldn't do the task right now. Nothing was charged: retry in a moment. |