OpenAPI overview

INFO

Beta OpenAPI is currently in closed beta and open only to selected partners. To request access, contact your account manager.

What is Lovrabet OpenAPI?

Lovrabet OpenAPI is a data API service built for enterprise applications. HMAC-SHA256 request signing keeps every transmission secure and tamper-proof.

When you need it

Use OpenAPI when you want to step outside the Lovrabet platform itself but keep reusing the Instant APIs, Backend Functions, and custom SQL you have already built — on a third-party platform, for example:

1. Standalone apps and mini programs
2. Existing enterprise systems with their own account and permission systems that need to read Lovrabet data

That's exactly what OpenAPI is for.

INFO

If you instead want to call Lovrabet platform data from an AI Agent client (such as Feishu, DingTalk, Claude Code, Codex App, WorkBuddy, Trae Work, and similar) and reuse the unified permission control of systems built with Lovrabet, use Lovrabet CLI: <cite doc-id="XHlRweKKNiaKgKkcAF5cErzlnDh" file-type="wiki" title="Lovrabet CLI - 业务流程AI化套件" type="doc"></cite>

:::

Key features

• 🔐 Secure authentication - HMAC-SHA256 signing with multiple auth modes
• 🚀 Works out of the box - the official SDK handles auth, signing, and token management
• 🌐 Runs anywhere - Node.js servers and browsers alike
• 📊 Powerful queries - pagination, sorting, and rich filtering
• 📝 TypeScript - full type definitions and editor hints
• 🛡️ Permission isolation - app-level data access control

Three authentication modes

OpenAPI offers three modes, depending on where your code runs and what it accesses:

1. Server-side mode - accessKey

Best for: Node.js servers, SSR, API routes

Generates a token on the fly from your accessKey — nothing to pre-generate:

import { createClient } from "@lovrabet/sdk";

const client = createClient({
  appCode: "your-app-code",
  accessKey: process.env.LOVRABET_ACCESS_KEY, // ✅ 从环境变量读取
  models: {
    users: { tableName: "users", datasetCode: "ds-001" },
  },
});

// 直接调用,SDK 自动处理认证
const users = await client.models.users.filter();

2. Browser token mode - pre-generated tokens

Best for: public data in the browser, anonymous users

Your server generates the token; the browser uses it:

// 步骤 1: 服务端生成 Token (如 Next.js API 路由)
import { generateOpenApiToken } from "@lovrabet/sdk";

export async function GET() {
  const result = await generateOpenApiToken({
    appCode: "your-app-code",
    datasetCode: "ds-001",
    accessKey: process.env.LOVRABET_ACCESS_KEY,
  });

  return Response.json(result); // { token, timestamp, expiresAt }
}

// 步骤 2: 浏览器使用 Token
const { token, timestamp } = await fetch("/api/token").then((r) => r.json());

const client = createClient({
  appCode: "your-app-code",
  token: token,
  timestamp: timestamp,
  models: { users: { tableName: "users", datasetCode: "ds-001" } },
});

3. Browser Cookie mode - user sessions

Best for: signed-in users reading private data

No credentials required — the browser's Cookies are used automatically:

const client = createClient({
  appCode: "your-app-code",
  models: {
    users: { tableName: "users", datasetCode: "ds-001" },
  },
});

// 请求会自动携带用户的登录 Cookie
const users = await client.models.users.filter();

TIP

Which mode should I use?

• On the server? → accessKey mode
• Browser + public data? → pre-generated token mode
• Browser + signed-in user? → Cookie mode

Use cases

1. Data integration and sync

Feed Lovrabet business data into your enterprise systems:

• BI reporting - sync into your data warehouse on a schedule and build management reports
• ERP integration - exchange data with your ERP system
• Data platforms - plug Lovrabet in as a data source for your enterprise data platform

2. Custom application development

Build your own apps on Lovrabet data:

• Mobile apps - back your mobile frontend with data APIs
• WeChat mini programs - ship lightweight business apps fast
• Web apps - build tailored web management systems

3. Analytics and data mining

Go deep on analytics with OpenAPI:

• Real-time monitoring - build live dashboards on business data
• Analysis - export data for statistics and mining
• Forecasting - predict business trends from historical data

4. Workflow automation

Automate business processes through the API:

• Scheduled tasks - run queries and exports automatically
• Event triggers - kick off processes when data changes
• Batch processing - churn through large query volumes efficiently

Current capabilities

INFO

Scope OpenAPI currently exposes full read and write — query, create, and update — with app-level data access. Delete is, for now, available only in WebAPI (Cookie) mode.

Available endpoints

OpenAPI exposes the following endpoints. Base URL: https://runtime.lovrabet.com

Endpoint	HTTP path	SDK method	Description
List records	POST /openapi/data/get-list	getList(params?, sortList?)	Paginated query with filtering and multi-field sorting
Get a single record	POST /openapi/data/get-one	getOne(id)	Full record details by ID
Create a record	POST /openapi/data/create	create(data)	Create a new record
Update a record	POST /openapi/data/update	update(id, data)	Update an existing record (partial updates supported)

TIP

Full specification For detailed parameters and request/response formats, see the API reference.

Calling the endpoints

// 批量查询(支持分页、排序、筛选)
const users = await client.models.users.filter(
  {
    currentPage: 1,
    pageSize: 20,
    status: "active", // 条件筛选
  },
  [
    { priority: SortOrder.DESC }, // 多字段排序
    { createTime: SortOrder.DESC },
  ]
);

// 查询单条数据
const user = await client.models.users.getOne(123);

// 创建数据
const newUser = await client.models.users.create({
  name: "John Doe",
  email: "john@example.com",
});

// 更新数据
const updated = await client.models.users.update(123, {
  status: "inactive",
});

Authentication

Every OpenAPI request is authenticated with an HMAC-SHA256 signature, carried in HTTP headers:

Header	Description	Example
X-Time-Stamp	Request timestamp (milliseconds)	1758903130713
X-App-Code	App code	app-c2dd52a2
X-Dataset-Code	Dataset code	0fefba76fe29440194841f4825df53ff
X-Token	HMAC-SHA256 signature	jdqqGtzecF2I6FIW...

The SDK handles all of this automatically — you never set these headers by hand.

Coming soon

• ⏳ Delete - a delete() method for OpenAPI mode (currently WebAPI only)
• ⏳ Webhooks - real-time push notifications on data changes
• ⏳ Bulk operations - batch create, update, import, and export
• ⏳ File uploads - upload and manage file fields

Response structure

Every OpenAPI endpoint returns the same envelope.

getList response format

{
  "success": true,
  "msg": "操作成功",
  "data": {
    "paging": {
      "pageSize": 10,
      "totalCount": 100,
      "currentPage": 1
    },
    "tableData": [
      {
        "id": "123",
        "name": "示例数据",
        "status": "active",
        "gmt_create": "2024-01-01 12:00:00"
      }
    ],
    "tableColumns": [
      {
        "title": "ID",
        "dataIndex": "id"
      },
      {
        "title": "名称",
        "dataIndex": "name"
      }
    ]
  }
}

Fixed fields:

• paging - pagination info (total count, current page, page size)
• tableData - the records themselves, as an array
• tableColumns - column definition metadata, handy for building UIs dynamically

Security best practices

Critical security note

Never expose an accessKey in browser code!

❌ Don't:

// 危险!会暴露密钥
const client = createClient({
  accessKey: "sk_live_xxx", // ❌ 切勿这样做!
});

✅ Do:

// 服务端:使用环境变量
const client = createClient({
  accessKey: process.env.LOVRABET_ACCESS_KEY,
});

// 浏览器:使用预生成的 token
const { token } = await fetch("/api/token").then((r) => r.json());
const client = createClient({ token });

Built-in safeguards

1. Token expiry - every token is valid for 10 minutes and dies after that
2. Signature verification - every request must carry a valid HMAC-SHA256 signature
3. HTTPS enforced - production traffic is always encrypted
4. App isolation - each app can only access its authorized datasets
5. Environment variables - secrets live in env vars, never in the repo

Data permissions

• App isolation - each app can only access its authorized datasets
• Field-level control - restrict access per field
• Row-level control - filter access per row

SDK support

To keep things simple, we ship an official SDK:

npm install @lovrabet/sdk
# 或
bun add @lovrabet/sdk

Why use the SDK:

• ✅ Auth and signing handled for you
• ✅ Automatic token lifecycle management
• ✅ Full TypeScript support
• ✅ Consistent error handling

Resources:

• npm package
• GitHub repository
• Full documentation

Getting access

1. Request access

Contact your account manager with the following:

• Your company name and a description of your business scenario
• Expected call volume and concurrency needs
• The list of datasets you need to access
• A technical contact

2. Receive your credentials

Once approved, you'll receive:

• App Code - your app's unique identifier
• Access Key - your access key (keep it secret)
• Dataset Codes - the datasets you're authorized to use

Technical specification

Endpoint conventions

• Protocol: HTTPS
• Method: POST
• Encoding: UTF-8
• Format: JSON

Environments

Environment	Domain
Production	https://runtime.lovrabet.com

Next steps

Ready to start? We recommend reading in this order:

1. Quick start - make your first API call in 5 minutes
2. Authentication guide - the three auth modes and token management in depth
3. API reference - full endpoint docs and advanced usage

TIP

Start with the quick start New here? Jump straight into the Quick start and learn from working examples.

Support and feedback

For technical support or any questions, reach us at:

• 📧 Technical support: ask your account manager for the support contact
• 📚 Developer docs: continuously updated
• 💬 Live chat: weekdays 9:00-18:00