Developer documentation

Overview

The Liberrex API lets your systems work with the AI agents you build in Liberrex AI & Agents: send messages to agents, read conversations and their transcripts, follow credit usage, start task agents from other systems and send interactions to Quality for scoring.

Interfaces

Core objects

Quick start

1. Create a key in Dashboard › API keys. Name it, optionally restrict it to a project, and select the read and execute access levels.
2. Copy the full key when it is shown: it is displayed only once. Store it in a secret manager or an environment variable, never in source code.
3. Call GET /api/v1/me to check the key, then GET /api/v1/agents to find an agent whose accepts_messages field is true.
4. Send a message with POST /api/v1/agents/{agent_uuid}/messages. Keep the returned session_id to continue the conversation.

GET /api/v1/health needs no key: use it to check that the service answers.

The API is available on plans that include API access — see your plan in Billing.

Authentication

Requests to /api/v1 are authenticated with a personal API key of the form key_id:secret. The key_id is public; the secret is shown once, when the key is created, and only its SHA-256 hash is stored.

Sending the key

Access levels

Each key holds one or more access levels, chosen when it is created. Each endpoint requires one level; admin grants every level.

Key owner, scope and plan

• A key acts for the person who created it, inside their workspace, with the permissions of their role. It is refused (401) as soon as the owner is deactivated or their role loses the API keys permission (manage:api_keys).
• Reading conversations also requires the read:transcripts permission on the owner's role; otherwise the API answers 403 forbidden.
• A key restricted to a project only sees the agents and conversations of that project. If the project is deleted, the key gets 403.
• A key stops working (401) when it is deactivated, deleted or past its expiry date.
• The API is available on plans that include API access — see your plan in Billing. On other plans, requests are refused with 403 and the code plan_required.

Security best practices

• Call the API from your servers only. Never put a key in a web page, a mobile app or a public repository: anyone holding it acts with your permissions.
• Create one key per integration, restricted to its project and to the access levels it needs (read only for reporting).
• Rotate keys: create the new key, deploy it, check it with GET /api/v1/me, then delete the old one.
• Keep keys out of URLs: do not use the api_key query parameter in production.
• Follow the requests made with each key in GET /api/v1/usage (api_key.requests_this_period) and delete keys you no longer use.

Requests and responses

Base URL and format

All paths are relative to https://ai-api.liberrex.com. Use HTTPS. Request and response bodies are JSON encoded in UTF-8.

POST requests with a body must send Content-Type: application/json: without it the body is not read and the API answers 400.

Response envelope

Every v1 response is a JSON object with a boolean success. On success the result is in data; on error the body holds a readable message and a stable code. Test the code in your integration, not the message.

Messages are in English. Send Accept-Language: fr or Accept-Language: ar (a bare language code) to receive them in French or Arabic; codes are never translated.

Unknown paths and wrong methods get 404 or 405 with success set to false and a message, but no code.

Data types

Pagination

Only GET /api/v1/conversations is paginated, with page (from 1) and per_page (1 to 100, default 20). The response carries a pagination object. Other lists return every item in scope in one response.

Filtering

Errors

Errors use standard HTTP status codes and the error envelope. The code field takes one of the values below.

Order of checks

1. Authentication (401). Refused keys are not counted against the rate limit.
2. Rate limit (429).
3. Access level, then owner permission (403 forbidden).
4. Plan (403 plan_required).
5. Validation and processing (400, 402, 404, 409, 500).

Every request that passes authentication is logged on the key and counted against its rate limit, including refused ones.

Rate limits

Each key may send a set number of requests per minute: 100 by default. The value is returned as rate_limit_per_minute by GET /api/v1/me and GET /api/v1/usage. The counter is shared by all servers and resets at the start of each clock minute.

The headers are sent on every response to an authenticated request, errors included. GET /api/v1/health is not rate limited.

Handling 429

• Wait for the number of seconds in Retry-After, then retry. A request refused with 429 was not processed, so retrying it is safe, POST included.
• Retry 500 errors on GET requests with exponential backoff. Do not blindly retry POST …/messages after a 500 or a timeout: the message may have been processed.
• Spread batch jobs over time and read X-RateLimit-Remaining to slow down before reaching the limit.

Agent webhooks and the chat widget have their own limits: see their sections.

Agent webhooks

Task agents with a Webhook trigger run when another system calls their URL. The webhook does not use API keys: it is protected by the agent secret. The published version of the agent runs, and the call returns when the run has finished.

Trigger URL

Copy the URL from the agent page (Guardrails tab, Webhook protection), or read webhook.url from the agent object in the API and prefix it with the base URL. The path holds the workflow uuid of the agent, not the agent uuid.

Request

Signature

To prove that a request comes from you without sending the secret, sign the exact bytes of the body:

X-Liberrex-Signature: sha256=<hex(HMAC-SHA256(key = agent secret, message = raw body))>

• Serialise the JSON once, sign that string and send that same string. Re-serialising after signing changes the bytes and the signature fails.
• The signature covers the body only and carries no timestamp, so a captured request can be replayed. Use HTTPS, keep the secret private and rotate it if it leaks.
• Without a secret the webhook accepts any call: create one before going to production.

import crypto from "node:crypto";

// What Liberrex computes for X-Liberrex-Signature (use it to test your signing code).
export function isValidSignature(rawBody, header, secret) {
  if (!header?.startsWith("sha256=")) return false;
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const given = header.slice(7);
  return given.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Limits

• Body: 1 MB at most.
• Each agent accepts 60 calls per minute by default (1 to 1,000, set in Webhook protection). Over the limit the webhook answers 429.

Responses

These responses do not use the v1 envelope: errors carry an error field and no code.

Quality ingestion API

Send e-mails, chats and call transcripts from your helpdesk, CRM or chat platform to Quality. Each interaction is queued and scored with your scorecards, like an upload.

Authentication

• Create the ingestion key in Quality › Settings › Ingestion API. It starts with lxqk_ and is shown once. There is one key per workspace: creating a new key replaces the previous one, and the key can be revoked.
• Send it as Authorization: Bearer lxqk_… or X-Quality-Key: lxqk_…. API v1 keys are not accepted here.
• Ingestion needs a plan that includes API access, room in the monthly Quality interactions allowance and credits for the analysis; otherwise the API answers 400 with a message that says which.

Request body

One interaction object, or {"interactions": [ … ]} with 1 to 100 interactions.

Interaction object

Message object

Without a role, authors are matched with the agent e-mail domains, addresses and chat names set in Quality settings; otherwise the first author is taken as the customer. When personal data masking is on in Quality settings, texts are masked before they are stored.

Duplicates

An interaction whose external_id was already received on the same channel is skipped and listed in duplicates. Interactions without external_id are never deduplicated: send one so that retries are safe.

Response

Status 201 when at least one interaction was created, 200 otherwise (all duplicates or refused).

Errors

Errors use {"success": false, "message": …}, without a code. Refused items of a batch carry one of: Not an object, channel must be one of call, email, chat, messages (with text) are required.

Website chat widget

A Website chat widget channel puts an agent on your website with one script tag. Create the channel in Channels, choose the agent that answers it, list the allowed websites and turn on incoming messages.

Embed

Paste the snippet shown in the channel setup before </body> on every page where the chat should appear. The script has no dependency and sets no cookie; it keeps the visitor session id in localStorage. Title, welcome message, colour and position (right or left) are set on the channel.

Public endpoints

To build your own chat interface, call the endpoints the widget uses. They need no API key: the widget key (lxwk_…) is public, so the allowed websites are what protects the channel.

Returns title, welcome, color, position and agent (the name of the agent answering).

The widget script, served with Access-Control-Allow-Origin: * and cached for 5 minutes.

Allowed origins and CORS

• Allowed websites are a comma-separated list of origins (scheme, host and port, e.g. https://www.example.com), compared exactly. An empty list allows every website: do not leave it empty in production.
• For allowed origins, OPTIONS preflight requests get 204 and responses carry Access-Control-Allow-Origin set to that origin. Requests from other origins get 403 without CORS headers, so the browser reports a CORS error.
• The check relies on the Origin header sent by browsers. Requests without Origin (server to server) are not checked: the widget key is not a secret.

Limits and errors

Channel webhooks

Messaging providers deliver incoming messages to this URL. The exact URL, verify token and settings are shown in the setup panel of each channel. The URL is built from the public address of the server (WEBHOOK_BASE_URL); providers require https.

Verification and responses

• Meta checks the URL with a GET request: when hub.mode is subscribe and hub.verify_token equals the verify token of the channel (lxvt_…), the endpoint answers 200 with hub.challenge as plain text, otherwise 403.
• On Meta channels without an app secret, events are accepted unsigned and the setup panel shows a warning: set the app secret.
• A wrong signature gets 403 Invalid signature and the event is not processed. An unknown channel gets 404.
• Accepted events get 200 (OK as plain text, or an empty TwiML response for SMS). Messages are processed in the background, only when the channel is active and incoming messages are on.

Platform mesh (MCP)

The platforms of your company (Liberrex AI, Animatoria, your ERP…) call each other’s tools over the Model Context Protocol. Every platform can publish tools (an MCP server) and call the tools of the others (an MCP client). Liberrex agents use connected platforms to read live data and, with a manager’s approval, to act there; the other platforms use Liberrex AI for its agents, copilot and sales recommendations.

Packages

Conventions

• Transport: MCP Streamable HTTP at /mcp, stateless with JSON responses, so any instance answers any call.
• Who calls: each calling platform has its own key, sent as Authorization: Bearer lxp_…. The server keeps only its SHA-256 hash, and limits each caller to some tenants, with or without write tools.
• For whom: each call carries the person it acts for (user, tenant, roles, locale) in _meta["com.liberrex/identity"]. The called platform applies that person’s own permissions; a model never chooses the identity.
• Tools declare their policy in _meta["com.liberrex/tool"]: the permission the person needs, and whether the tool changes data. Write tools are refused to callers without writes.
• Errors are tool errors whose text starts with a code: [unauthorized] [identity_required] [tenant_not_allowed] [forbidden] [writes_disabled] [invalid_request] [not_found] [conflict] [rate_limited] [too_many_hops] [upstream_error] [internal_error].
• A call can go through at most 4 platforms: each hop adds one to the trace, and servers refuse more.

Connect a platform to Liberrex

Once a platform publishes its tools, connect it in the dashboard so that your agents can use them.

1. On that platform, issue a key for Liberrex and list Liberrex among its callers, with the tenants it may act in and whether it may write.
2. In Liberrex, open Developers › Connected platforms › Connect a platform. Enter a name, a platform id (it prefixes the tool names, e.g. animatoria_production_overview), the MCP address and the key.
3. Choose the service user: the user and tenant your agents act as on that platform, and their roles. Calls see exactly what this user sees there, so pick a user with the access the agents need, no more.
4. Choose what agents may do: read only, or read and write. Write tools are never offered on a read-only connection.
5. Save: the tools are synced at once. The connection card shows its status, its tools (read and write) and the last error, if any. Sync again after the platform adds tools.

Security

• Addresses must use https:// and may not point to internal networks. For local development only, MCP_ALLOW_PRIVATE_NETWORK=1 on the Liberrex server accepts http://localhost.
• The key is encrypted at rest and never shown again (only its first characters). Managing connections needs the Manage keys & secrets permission; viewing them, View keys & secrets.
• Each call times out after 25 seconds (MCP_CALL_TIMEOUT). Results are passed to the model as data: text that reads like instructions is flagged.

Publish your platform’s tools

Declare functions as tools: their typed parameters become the input schema, and a context parameter tells who calls and for whom. Mount the server at /mcp in your web app, or run it on its own.

Checks done before your function runs

Already integrated with the Liberrex copilot?

Every tool declared with the copilot SDK can be published in one line, with the same schemas, permissions and errors. Your platform computes the person’s roles itself instead of trusting the roles the caller sends. This is how Animatoria publishes its tools.

Callers

List the platforms allowed to call you in LIBERREX_MCP_PEERS: for each, the SHA-256 of its key, the tenants it may act in ("*" for all), whether it may call write tools, and optionally a ceiling on the roles it may pass. Give each caller its own key.

• A caller can have several keys: add the new key, let the caller switch, then remove the old one. A key with an expiry date stops working at the end of that day (UTC).
• Each caller has a budget of tool calls per minute (rate_per_minute, 120 by default); over it, calls are refused with [rate_limited], and a flood of HTTP requests is answered with 429.
• Put the callers in a file named by LIBERREX_MCP_PEERS_FILE: it is re-read when it changes, so a caller is revoked or its key rotated without a restart. If the file becomes invalid, the previous callers stay in force.
• Every call, allowed or refused, produces an audit event (tool, caller, person, tenant, trace id, status, duration), never the arguments. By default it is one JSON line in the log; pass your own audit function to send it to your SIEM.

# Several keys (rotation with overlap), an expiry date and a call budget per caller.
# In a file, the callers are re-read when it changes: revoke or rotate without a restart.
LIBERREX_MCP_PEERS_FILE=/etc/liberrex/mcp-peers.json

{"liberrex-ai": {"keys": [{"key": "sha256:9f86…", "expires": "2027-01-31"}, "sha256:4e07…"],
                 "tenants": ["acme"], "writes": true, "rate_per_minute": 300}}

{"event": "tool_call", "platform": "animatoria", "tool": "create_mission", "write": true,
 "status": "ok", "peer": "liberrex-ai", "user": "42", "tenant": "acme",
 "trace_id": "5f1c…", "hops": 1, "duration_ms": 184, "at": "2026-10-16T09:12:03Z"}

Call other platforms

List the platforms you call in LIBERREX_MCP_PLATFORMS (address and the key each one issued for you) and name your own platform in LIBERREX_MCP_PLATFORM. Each call sends the identity of the signed-in person: set it in your code, never from a model.

• A tool error raises PlatformToolError with its code (forbidden, not_found, writes_disabled…); an unreachable platform or a refused key raises PlatformUnavailable.
• The Python client has async calls and sync versions for Flask, Celery or scripts; tool lists are cached for 5 minutes.
• To give tools to an LLM, convert them to OpenAI or Anthropic tool definitions: names become platform__tool, and route maps a model’s call back to the platform and tool. Ask a person before running a write tool.

The Liberrex AI MCP server

Liberrex AI publishes its own tools on the mesh: other platforms (or a desktop MCP client) can use its agents, its embedded copilot and its sales recommendations. Run it next to the Liberrex API.

• Copilot and sales tools act for the person each call names: Liberrex opens a copilot session for that user and tenant with their roles. Recommendation modes map to surfaces, e.g. LIBERREX_SURFACES=next_best_action=nba-queue,next_best_product=nbp-queue.
• Writes are always two steps: a tool returns a confirmation card, and only confirm_action runs it, after the person approved it. LIBERREX_MCP_READ_ONLY=1 removes the tools that change data.
• Over HTTP the server needs LIBERREX_MCP_PEERS (the platforms allowed to call it); over stdio it acts as LIBERREX_USER_ID in LIBERREX_TENANT_ID.

Agents that use connected platforms

On an agent, open Connected platforms and choose which connections and tools it may use (all tools or a selection). Changes go live when the agent is published. The tools join the agent’s other tools on every message.

Approval of actions

• A write tool never runs on the first call: it is recorded as a proposed action with an id (A1, A2…), and the agent asks the person to confirm.
• When the person answers yes in their next message, the agent calls confirm_actions with the approved ids: each action runs exactly as proposed, once. Several actions can be approved with one yes; a proposal expires after two messages.
• Scheduled runs cannot approve anything: they can only propose actions, to be approved in a conversation.
• On a connection, choose who approves: a team member (the default) or the customer in the conversation. A team member must be signed in and hold the Approve agent actions permission (managers and administrators have it); the approval is recorded with their name.
• If a platform’s answer contains text that tries to give the agent instructions, the agent can no longer change anything for the rest of that message: proposals and approvals are refused, reading still works.

Routines

• An agent can have several Schedule steps, its routines (e.g. a daily brief, a Monday review, a monthly review). Each runs from its own step, with its own e-mail or delivery step.
• What a routine writes is kept with its run. A chat step can recall the latest reports (recall_reports), so the agent can follow up on what it proposed: “where are the decisions of Monday’s review?”.
• Test them in the agent’s Test tab › Routines: pick a routine and run it now. Test runs never send e-mails; they show the e-mail that would be sent.

Tool budget

By default a message allows 4 model rounds and 6 tool calls. Analysis agents can raise it on their chat step with tool_limits: {"rounds": 6, "calls": 12} (up to 8 rounds and 16 calls).