Developer

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
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"
}'
FieldWhat it is
messageThe person's message, up to 20 KB. Required, unless the request follows a tool call (the history ends with its results).
historyThe 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).
instructionsThe tone and the task, up to 20 KB ("you answer FP's sales team"). They never override Lid's rules.
contextYour system's data that Lida needs, as text or an object, up to 200 KB. Lida treats it as data.
guidesUp 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.
toolsUp to 20 of your system's tools, each with name, description and parameters (a JSON schema of type object, without pattern).
imagesUp to 5 images, each with mimeType (JPG, PNG, WebP or GIF) and base64 data, as in tasks.
schemaOptional: a JSON schema for the reply, of type object and without pattern. If Lida doesn't follow it, the turn fails without charging.
localees or en, the reply's language (es if you don't send it).
timeZoneYour time zone (like America/Mexico_City), for today's date and time; without it, UTC.
nameOptional: the name your assistant introduces itself with, up to 40 characters.
streamtrue 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.

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

JSON
{
  "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).

TypeStatusMeaning
lida_key_invalid401The 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_invalid400The request is outside a limit or a shape; details.field and details.reason say which. It isn't charged.
lida_no_credits402Your 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_browser403The 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_limit429Your account reached its daily Lida via API limit (account_day); details.resetsAt says when it comes back.
lida_unavailable503Lida 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
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"
    ]
  }
}'
FieldWhat it is
taskdetect (detect an order) or extract (extract its data). Required.
systemThe instructions for Lida, up to 50 KB. Required.
contextOptional context, up to 100 KB.
textThe text to check. Required if you send no images.
imagesOnly with extract: up to 5 images, each with mimeType (JPG, PNG, WebP or GIF) and data in base64.
schemaThe exact shape of the reply: a JSON schema with type object, up to 100 KB and without pattern. Required.
maxOutputTokensOptional, 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.

JSON
{
  "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.

JSON
{
  "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"
  }
}
TypeStatusMeaning
lida_key_invalid401The 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_invalid400The task is outside the limits (the type, texts, images or schema); details.field says which. Nothing is charged.
lida_no_credits402The account's balance isn't enough, or the key reached its monthly cap (details.reason key_cap). The task doesn't run.
lida_daily_limit429The account reached its task limit for today; it works again tomorrow.
lida_unavailable503Lida couldn't do the task right now. Nothing was charged: retry in a moment.