REST API

The Lotics API gives you programmatic access to everything in your workspace. Create records, query data, trigger workflows, generate documents, and receive real-time notifications -- all through a standard REST interface with an OpenAPI 3.1.0 specification.

Overview

• Protocol: Standard REST. Resources are nouns, HTTP methods are verbs, responses use standard HTTP status codes.
• Specification: OpenAPI 3.1.0, published at https://api.lotics.ai/v1/openapi.json.
• Base URL: https://api.lotics.ai/v1
• Content type: All requests and responses use application/json.
• Date format: ISO 8601 strings in UTC (e.g., 2026-04-04T12:00:00.000Z).
• Record field values: Follow the same types as the Lotics interface -- text, number, date, select, multi-select, linked records, files, and computed fields (formula, rollup, lookup).

Every entity you interact with in the Lotics interface (tables, records, views, workflows, document templates, apps, files) is available through the API. The API is the same interface that the Lotics web application uses internally, so every feature available in the UI is also available through the API.

Authentication

API requests are authenticated with organization-scoped API keys.

Sending the key

Include the key in the Authorization header on every request:

Authorization: Bearer ltk_your_key_here

Error responses

Security best practices

• Keys are shown once at creation. Copy and store them securely (e.g., environment variables, secrets manager).
• Give each key a descriptive name (e.g., "Production sync", "CI/CD pipeline") for easy identification.
• If a key is compromised, disable it immediately from Settings -> API Keys and create a new one.
• Use separate keys for different environments (production, staging, development).

Available endpoints

The API provides full CRUD operations for all primary entities, plus specialized operations like record aggregation, document generation, and global search.

Record queries

Record queries are executed server-side with the same filter engine used by the Lotics interface. Complex filters (nested AND/OR conditions, linked record lookups, date comparisons) perform identically through the API and in the app. There is no client-side filtering overhead regardless of table size.

Pagination

All list endpoints use cursor-based pagination for consistent results even during concurrent writes.

How it works

1. Make your initial request without a cursor parameter.
2. If more results exist, the response includes a next_cursor field.
3. Pass the next_cursor value as the cursor query parameter in your next request.
4. Repeat until next_cursor is absent, meaning you have reached the last page.

Cursor-based pagination ensures stable ordering even when records are created or deleted between pages.

Rate limits

The API enforces rate limits to ensure fair usage and consistent performance.

When you exceed the rate limit, you receive a 429 Too Many Requests response with a Retry-After header indicating when to retry (in seconds). Implement exponential backoff in your client for best results. Contact support if your use case requires higher limits.

Error responses

All error responses follow a consistent JSON structure:

{
  "error": {
    "code": "not_found",
    "message": "Record not found"
  }
}

Webhook events

Register webhook endpoints to receive real-time notifications when data changes. Lotics sends an HTTP POST to your URL within seconds of a change occurring.

Available event types

Webhook behavior

• Filtering: Each webhook registration can filter by table and event type so you only receive relevant notifications.
• Payload: Events include the full record data before and after the change, so you can react to specific field updates without polling.
• Signature: Payloads include a signature header for verification. Validate the signature to ensure the webhook came from Lotics.
• Retries: Failed deliveries are retried with exponential backoff for up to 24 hours.
• Monitoring: View delivery logs and manually retry failed deliveries from Settings -> Webhooks.
• Auto-disable: If an endpoint consistently fails, Lotics disables it and sends an email notification to the organization admin.

MCP Server

Lotics provides a Model Context Protocol (MCP) server that exposes the same capabilities as the REST API through the MCP standard. This allows AI assistants and LLM-based tools to interact with your Lotics data directly.

See the dedicated MCP Server documentation for setup instructions and available tools.

CLI and SDK

Lotics provides a command-line interface and Node.js SDK for scripting, automation, and integration.

Installation

npm install -g @lotics/cli

Node.js SDK

import { LoticsClient } from "@lotics/cli";

const client = new LoticsClient({
  apiKey: "ltk_your_key_here",
});

// List tables
const tables = await client.tables.list();

// Query records with filters
const records = await client.records.query("table_id", {
  filters: { field: "status", operator: "eq", value: "active" },
  limit: 50,
});

// Create a record
const record = await client.records.create("table_id", {
  values: { name: "New item", status: "draft" },
});

See CLI reference for the full command-line documentation.

OpenAPI specification

The OpenAPI 3.1.0 specification is published at:

https://api.lotics.ai/v1/openapi.json

Import this spec into tools like Postman, Insomnia, or any OpenAPI-compatible code generator to get typed client libraries in your preferred language. The spec stays in sync with the API -- when new endpoints ship, the spec updates automatically.

Use openapi-generator to generate typed SDKs in TypeScript, Python, Go, Java, and other languages:

npx @openapitools/openapi-generator-cli generate \
  -i https://api.lotics.ai/v1/openapi.json \
  -g typescript-fetch \
  -o ./lotics-client

Common use cases

• System sync: Keep Lotics in sync with external systems (ERP, CRM, e-commerce) by pushing and pulling records through the API.
• Custom dashboards: Build dashboards that pull live data from Lotics tables using query and aggregate endpoints.
• Automated record creation: Create records from external events -- form submissions, payment confirmations, shipping updates.
• Report generation: Query and aggregate record data programmatically to generate reports.
• Document automation: Fill document templates with record data to produce PDFs and Excel files on demand.
• CI/CD integration: Use API keys in pipelines to create records, update statuses, or trigger workflows as part of your deployment process.

Frequently asked questions

Is there a rate limit on the API?

Yes. Standard rate limits are 100 requests per second per API key with burst capacity for short spikes. Rate-limited requests receive a 429 response with a Retry-After header. Contact support if your use case requires higher limits.

Can I use the API to create workflows programmatically?

Yes. The workflows endpoint supports full CRUD. You can create triggers, define steps (including conditionals, loops, and AI actions), and deploy workflows entirely through the API. Workflow execution history is also available via the API.

How do I handle file uploads through the API?

Use the Files upload endpoint with a multipart/form-data request. The response returns a file ID that you can assign to a file field when creating or updating records. File download URLs are signed and time-limited for security.

Can I test the API without affecting production data?

Create a separate organization for development and testing. API keys are organization-scoped, so your test key will only access test data. There is no additional cost for development organizations.

Is the OpenAPI spec available for code generation?

Yes. The OpenAPI 3.1.0 spec at https://api.lotics.ai/v1/openapi.json can be imported into tools like openapi-generator, Postman, or any OpenAPI-compatible client to generate typed SDKs in TypeScript, Python, Go, Java, and other languages.

How does cursor pagination differ from offset pagination?

Cursor pagination uses an opaque token (next_cursor) instead of page numbers. This ensures consistent results even when records are created or deleted between requests. With offset pagination, insertions and deletions can cause you to skip records or see duplicates. Cursor pagination avoids these problems entirely.

What happens if my webhook endpoint is down?

Lotics retries failed webhook deliveries with exponential backoff for up to 24 hours. If your endpoint consistently fails, Lotics disables the webhook and notifies your organization admin via email. You can view delivery logs and manually retry from Settings -> Webhooks.

Can AI assistants interact with the API?

Yes. The MCP Server exposes the same capabilities as the REST API through the Model Context Protocol standard. AI assistants and LLM-based tools can query data, create records, trigger workflows, and generate documents. See the MCP Server documentation for setup.

How do I filter records by multiple conditions?

The query endpoint supports nested AND/OR filter groups. Each filter specifies a field, operator, and value. You can combine filters into groups with and/or logic. The filter engine is the same one used in the Lotics interface, so any filter you build in the UI can be replicated through the API.

What field types are supported?

All field types available in the Lotics interface are supported through the API: text, number, date, select, multi-select, checkbox, linked records, files, formula, rollup, and lookup. Computed fields (formula, rollup, lookup) are read-only -- their values are calculated automatically based on their configuration.