Lapis API reference

1. Sign up on the Lapisan Console with your work email. A link signs you in.
2. Copy your test key. A test key (ax_test_…) and a sandbox business are ready at once. Keep the key on your server, never in a web page or an app.
3. Make your first call. List the sandbox business's documents, then make an invoice. With a test key every write is a dry run: it answers as live would, with "test": true, and keeps nothing.

export LAPIS_KEY=ax_test_...

curl "https://api.antarax.ai/lapis/v1/documents?limit=5" -H "Authorization: Bearer $LAPIS_KEY"

curl https://api.antarax.ai/lapis/v1/documents \
  -H "Authorization: Bearer $LAPIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "invoice", "customer": { "name": "Kedai Runcit Ali" }, "lines": [ { "description": "Roll-up banner", "quantity": 3, "unit_price": "150.00" } ] }'

4. See it in the Console. Your calls show in the Lapisan Console, under your sandbox business. When you are ready, ask for live access there; AntaraX approves it and you make live keys (ax_live_…).

Already on Lapis? Keep making keys in Lapis, under Settings → Developers, or link your Lapis account in the Console with the same email.

Building for many businesses at once? Read the Lapisan Connect guide: each business approves your app once, and you call for them with your own key.

Sign up on the Lapisan Console for a test key and a sandbox business at once; live keys come once AntaraX approves your request there. A Lapis account's owner can also make keys in Lapis, under Settings → Developers, and link that account in the Console with the same email. A key is shown once, when it is made; keep it on your server and never in a browser or an app.

Each key has the permissions it was given and nothing more:

• lapis:documents:read to read documents and their PDFs, and to verify documents
• lapis:documents:write to make, send and cancel documents
• lapis:payments:write to record payments
• lapis:customers:read to read customers and their statements
• lapis:webhooks:write to make and change webhook endpoints, and to read events
• lapis:connections:read and lapis:connections:write, for Lapisan Connect: to see and end the connections other accounts gave your apps, and to swap an approval's code

Call https://api.antarax.ai/lapis/v1, then the path. Send the key as a bearer token on every call. Bodies are JSON.

curl https://api.antarax.ai/lapis/v1/documents -H "Authorization: Bearer ax_live_..."

Every answer carries X-Request-Id (quote it when you ask us about a call) and AntaraX-Version, the date of the shape you are getting.

The key goes in the header and nowhere else. A key in the address (?key=, ?api_key=, ?token= and the like) is refused with 400 key_in_url without being looked up, because addresses end up in logs: stop that key and make another. Bodies over 1 MB are refused with 413 payload_too_large.

Keys start ax_test_ or ax_live_. A test key reads the account's real documents and customers, and every write is a dry run: it is checked and worked out exactly as a live call would be, and answered in the same shape with "test": true. Nothing is kept and nobody is emailed. A dry run counts what live would have used (a document issued, an email, a payment) as test usage, so you can see what live would cost; test usage is never capped or billed. A dry run has no url or pdf, since nothing was made, and its events go to the account's test endpoints.

A live key does the real thing: documents are numbered and kept, emails go, money is recorded.

• Money is a string with two decimals beside an ISO currency: "total": "486.00", "currency": "MYR". Send it the same way. Never a number, so nothing is lost to rounding.
• Days are YYYY-MM-DD. Moments are ISO 8601 in UTC.
• Ids carry their kind: ldoc_ for documents, lpay_ for payments, lcus_ for customers.
• Lists are { "data": [...], "next": "..." }. Pass next back as cursor until it is null.
• Fields this API does not know are refused, so a misspelt one never passes quietly.

Every error has the same shape, and its message is a sentence a person can act on.

{ "error": { "code": "number_taken", "message": "INV-2026-0088 is already on another invoice. The next free number is INV-2026-0089.", "request_id": "req_..." } }

Each key may make so many calls a minute, set by the account's plan; X-RateLimit-Limit and X-RateLimit-Remaining say where you are. Over it, the answer is 429 with Retry-After in seconds.

Live calls also count towards a daily and a monthly allowance for the account. Where the cap is hard, calls past it get 429 cap_reached; where it is soft, they are answered with an AntaraX-Cap-Warning header. Test calls are never capped.

AntaraX can pause the API for everyone, for Lapis, for one account or for one key; paused calls get 503 switched_off with the reason.

Send an Idempotency-Key header on a write (any string you choose, up to 120 characters, such as your own order id). If the same call is sent again with the same key and the same body, you get the first answer back, with Idempotent-Replayed: true, and nothing is made twice. The same key with a different body is refused with 422 idempotency_mismatch. A copy that arrives while the first is still running gets 409 idempotency_in_progress: wait for Retry-After and send it again.

Lapis can tell your systems when something happens, instead of you asking. Make an endpoint in Settings → Developers or with POST /webhook_endpoints, and each event is sent to it as a POST with a JSON body, one event a request.

Every event has the same envelope. data.object is the document as it was at that moment, in the same shape the API answers with; lapis.payment.recorded carries the invoice after the payment. Events come from everything that happens to the account's paper, in Lapis itself and through the API alike.

POST /hooks/lapis
Content-Type: application/json
AntaraX-Signature: t=1791015262,v1=5f1c0e...a94b

{
  "id": "evt_2c8d41f0a9b34e6c8d7e1f2a3b4c5d6e",
  "type": "lapis.payment.recorded",
  "created": "2026-10-05T08:14:22Z",
  "api_version": "2026-10-01",
  "product": "lapis",
  "tenant_id": "lacc_...",
  "data": { "object": { "id": "ldoc_m1x2k3", "object": "document", "status": "paid", "owed": "0.00", ... } }
}

Check the signature. AntaraX-Signature is t= the time in Unix seconds and v1= the HMAC-SHA256, in hex, of the time, a full stop and the raw body, keyed with the endpoint's secret (ax_whsec_…, shown once when the endpoint is made). Turn away anything that does not match or is more than five minutes old. In Node:

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

// Checks a delivery against the raw body, exactly as it arrived.
function verifyLapisWebhook(rawBody, header, secret, toleranceSeconds = 300) {
  let t = null;
  const signatures = [];
  for (const part of (header ?? "").split(",")) {
    const [k, v] = part.trim().split("=", 2);
    if (k === "t") t = Number(v);
    if (k === "v1") signatures.push(v);
  }
  if (!t || signatures.length === 0) return false;
  // Older than five minutes: a replay, not a delivery.
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return signatures.some((s) => {
    const given = Buffer.from(s, "hex");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

const app = express();

// Keep this route's body raw: parsed and printed again, it would not match.
app.post("/hooks/lapis", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifyLapisWebhook(raw, req.get("AntaraX-Signature"), process.env.LAPIS_WEBHOOK_SECRET)) return res.sendStatus(400);
  const event = JSON.parse(raw);
  // At least once: skip an event.id you have handled already.
  if (event.type === "lapis.payment.recorded") {
    const invoice = event.data.object; // the document, as the API shows it
    console.log(invoice.number, invoice.status, invoice.owed);
  }
  res.sendStatus(200); // answer quickly; do slow work afterwards
});

• Answer with any 2xx within 10 seconds. Redirects are not followed: give the final address.
• Delivery is at least once and in no promised order: de-duplicate on id, and trust created and the object's own state over the order things arrive in.
• A delivery that fails is tried again about 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours after the event, then given up. Retries run on a 10-minute schedule, so each comes at the first run after its time: up to 10 minutes later than the figure.
• An endpoint where 20 deliveries in a row fail is switched off, with the reason, until you switch it on again. Its log shows every try, with the code and the time, and Retry now.
• Test keys and test endpoints go together: a dry run's events go to test endpoints only, and live events to live endpoints only.
• Events and their deliveries are kept 30 days; GET /events lists them for catching up.

For software that works for many businesses, such as a point of sale, a booking system or an accounting tool. Each business keeps its own Lapis account and approves your app once; from then on you call with your own key and say which account with one header. Their paper stays theirs: numbered in their sequence, in their look, emailed from them. Lapisan Connect is part of Lapisan, the AntaraX developer platform; Lapis is the first product on it, and others follow the same steps.

1. Register an app in Lapis, under Settings → Developers → Lapisan Connect (your account needs the API on): its name, website and logo, the addresses people go back to (matched exactly; http://localhost only for test), and what it asks each account for. Its client_id is app_….
2. Send the owner to the authorize link. The page is Lapisan's, on Lapis's host for now (it moves to lapisan.antarax.ai/connect once AntaraX has one shared sign-in). They sign in to Lapis by email, or get a free account on the spot, and see your app, the business it will act for, each permission in plain words, and test or live. It never shows inside a frame.
3. Approve sends them to your redirect_uri with code and your state; Cancel with error=access_denied. A bad link (unknown app, an address you did not register, no state) is explained on the page and sends nobody anywhere.
4. Swap the code on your server with POST /connect/token and your key. The answer is the connection, with the account id to keep.
5. Call for them with AntaraX-Account: <account>. The call runs as their account, with what both your key and their approval allow.

1. Your app sends the account's owner to:
   https://angka.antarax.ai/lapis/connect/authorize?client_id=app_...
     &redirect_uri=https://yourapp.com/lapis/callback
     &scope=lapis:documents:read lapis:documents:write
     &state=<a fresh random value you keep>
     &mode=live            (or test)

2. They sign in to Lapis (a new address gets its free account),
   see your app and what it asks for, and press Approve.

3. Lapis sends them back to:
   https://yourapp.com/lapis/callback?code=axc_...&state=<yours>
   (Cancel: ?error=access_denied&state=<yours>)

4. Your server checks state, then swaps the code (10 minutes, once):
   POST https://api.antarax.ai/lapis/v1/connect/token
     { "code": "axc_...", "redirect_uri": "..." }
   -> { "object": "connection", "account": "lap_...", ... }

5. Every call for them: your own key, and their account.
   Authorization: Bearer ax_live_...   (yours)
   AntaraX-Account: lap_...            (theirs)

curl https://api.antarax.ai/lapis/v1/documents \
  -H "Authorization: Bearer $PARTNER_KEY" \
  -H "AntaraX-Account: lap_mh2k3x9" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8812" \
  -d '{ "type": "invoice", "customer": { "name": "Kedai Runcit Ali" }, "lines": [ { "description": "Banner", "unit_price": "150.00" } ] }'

• Test and live. A connection is one or the other, as the link said (mode=test), and works only with keys of the same mode. A test connection reads the account's real paper, and everything your test key makes for it is a dry run, as always.
• Limits and paying. Calls you make for connected accounts count against your own plan (rate per key, daily and monthly caps), not theirs. While the pilot is free, nothing is charged.
• Repeats. An Idempotency-Key is kept per account you act for, so the same key sent for two accounts runs once for each.
• Your own things stay yours. Webhook endpoints, events and connections are always your own account's; with AntaraX-Account they answer 403 connection_scope.
• Disconnects. The owner can disconnect in Lapis, under Settings → Connected apps (with a reason, which you are sent); you can with DELETE /connections/{id}; AntaraX can, and can pause an app. After that, calls get 403 connection_missing. A suspended account turns every connected call away.
• Webhooks for connected accounts. Their events also go to your own endpoints in the same mode, when the connection may read what they carry: tenant_id is their account, and the envelope adds "connection": "conn_…". lapis.connection.created and lapis.connection.revoked go to your endpoints only, carrying the connection.
• Errors. 400 invalid_account (not an account id), 400 invalid_code (a code unknown, used, late, for another app or address, or the other mode), 403 connection_missing (no working connection in the key's mode, or the app is paused), 403 connection_scope (not granted).

Lapis is also an MCP server, on the same keys: https://api.antarax.ai/lapis/v1/mcp. An assistant that speaks MCP over HTTP can list and read documents, make and send them, record payments, cancel, read customers and their statements, and verify paper. Each tool needs the same permission as its endpoint here, and counts the same; with a test key every write is a dry run, which is the safe way to start.

For Claude Code, in the project's .mcp.json (or the same entry in another client's settings):

{
  "mcpServers": {
    "lapis": {
      "type": "http",
      "url": "https://api.antarax.ai/lapis/v1/mcp",
      "headers": { "Authorization": "Bearer ${LAPIS_KEY}" }
    }
  }
}

Or from the command line:

claude mcp add --transport http lapis https://api.antarax.ai/lapis/v1/mcp --header "Authorization: Bearer ax_test_..."

The tools are list_documents, get_document, create_document, send_document, record_payment, cancel_document, list_customers, customer_statement and verify_document, each with the input this reference describes. Give the assistant a key with only the permissions it needs: a key that may only read cannot be talked into issuing anything.

Every field of every request and answer is in openapi.json, an OpenAPI 3.1 document made from the same schemas the API checks with. Load it into Postman, Insomnia or a client generator. It needs no key.