Introduction

Lerty is a chat interface that lets you deploy AI agents and automation workflows for yourself or an end user. It's also a notification and approval layer — surface alerts from your workflows and let users approve actions directly from their phone or desktop.

Base URL

https://lerty.ai/api/v1

What's an Agent?

You might call it a bot, assistant, workflow, or automation — in Lerty, we call it an Agent. Think of it as the conversation layer that sits between your users and whatever powers the responses, whether that's an AI model, an n8n workflow, a custom backend, or anything else.

Lerty supports two types of agents:

• Custom Agent - Uses built-in LLM providers (Anthropic, OpenAI, Google, Xai, OpenRouter) to handle conversations automatically
• Webhook Agent - Forwards messages to your backend via HTTP webhooks for custom processing (typically used to surface a front end for automations and agents on platforms like n8n, Flowmattic, Make.com, Zapier, Pipedream, etc.)

Authentication

All API requests require authentication using an API key in the Authorization header.

curl -X GET "https://lerty.ai/api/v1/agents" \
  -H "Authorization: Bearer ak_your_api_key_here"

Getting an API Key

1. Log in to Lerty at lerty.ai
2. Go to the Settings of your organization → API Key
3. Copy the api key.

Organizations

Organizations are how you group agents, conversations, and team members in Lerty. Every agent belongs to an organization, and you can invite team members to collaborate.

Sharing Access

Invite team members to your organization so they can:

• Chat with agents and receive notifications on their own devices
• Respond to human-in-the-loop approvals and interactive messages
• View conversation history and agent activity
• Manage agents and settings (admin role)

Member Roles

Custom Agent

Custom Agents use Lerty's built-in LLM integrations to automatically respond to messages. Agents can be configured with a system prompt to give your agent instructions and you can surface MCP server tools to your agents.

Supported Providers

Webhook Agent

Webhook Agents forward user messages to your backend or automation platform via HTTP webhooks. Use this to connect Lerty to n8n, Make.com, Zapier, FlowMattic, Pipedream, or any custom backend.

How It Works

1. User sends a message in Lerty
2. Lerty POSTs the message to your webhook URL
3. Your automation or backend processes the message
4. Your workflow calls Lerty's API to send a response
5. The user sees the response in real-time

Example Use Cases

• n8n workflow that queries a database and responds with results
• Make.com scenario that creates tickets in your helpdesk
• Custom backend that routes to different AI models based on intent

Webhook Payload

{
  "event": "message.created",
  "conversationId": "conv-uuid-here",
  "messageId": "msg-uuid-here",
  "agentId": "agent-uuid-here",
  "content": "Hello, I need help",
  "userId": "user-uuid-here",
  "userEmail": "user@example.com",
  "timestamp": "2024-01-15T10:30:00Z"
}

Agents

Retrieve agent configuration, update webhook URLs, and manage agent settings.

          curl -X GET "https://lerty.ai/api/v1/agents?detailed=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

          {
  "agents": [
    {
      "id": "agent-uuid-here",
      "name": "Support Bot",
      "status": "active",
      "protocol": "webhook",
      "webhook_url": "https://your-server.com/webhook"
    }
  ]
}

        

          curl -X GET "https://lerty.ai/api/v1/agents/AGENT_ID?detailed=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

          curl -X PATCH "https://lerty.ai/api/v1/agents/AGENT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://your-new-webhook.com/handle", "enabled": true}'

        

          {
  "success": true,
  "agent": {
    "id": "agent-uuid-here",
    "name": "Support Bot",
    "webhook_url": "https://your-new-webhook.com/handle",
    "enabled": true
  }
}

        

          curl -X GET "https://lerty.ai/api/v1/agents/AGENT_ID/connection-info" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

          {
  "connection_info": {
    "agent_id": "agent-uuid-here",
    "agent_name": "Support Bot",
    "webhook_url": "https://your-server.com/webhook",
    "protocol": "webhook",
    "conversations": [...],
    "api_endpoints": {
      "send_message": "https://lerty.ai/api/v1/agents/{id}/messages",
      "create_conversation": "https://lerty.ai/api/v1/agents/{id}/conversations/create"
    }
  }
}

        

Conversations

A conversation is a thread between your agent and a user. Create conversations programmatically to start new threads from your backend.

          curl -X POST "https://lerty.ai/api/v1/agents/AGENT_ID/conversations/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Support Request", "user_id": "USER_UUID"}'

        

          {
  "success": true,
  "conversation": {
    "id": "conv-uuid-here",
    "user_id": "user-uuid-here",
    "agent_id": "agent-uuid-here",
    "title": "Support Request",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

        

          curl -X GET "https://lerty.ai/api/v1/agents/AGENT_ID/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

Messages

Send messages into conversations. For Webhook Agents, use the originate endpoint to send responses back to users.

          curl -X POST "https://lerty.ai/api/v1/conversations/CONV_ID/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, I need help"}'

        

          curl -X POST "https://lerty.ai/api/v1/conversations/CONV_ID/originate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hi! How can I help you today?", "role": "assistant", "external_message_id": "msg-12345"}'

        

          {
  "success": true,
  "message": {
    "id": "msg-uuid-here",
    "content": "Hi! How can I help you today?",
    "role": "assistant"
  }
}

        

          {
  "error": "duplicate_message",
  "message": "Message with this external_message_id already exists"
}

        

Interactive Messages

Interactive messages enable human-in-the-loop workflows — collect approvals, gather structured input, or present choices before your automation proceeds. Perfect for expense approvals, confirmation dialogs, data collection forms, and any workflow that needs human oversight.

Example Use Cases

• Manager approves expense before n8n workflow processes payment
• User confirms shipping address before order is placed
• Team lead selects priority level for incoming support ticket
• Employee submits PTO request form, HR approves in Lerty

How It Works

1. Your workflow sends an interactive message to a conversation via the API
2. The user sees the interactive UI (buttons, form, or approval prompt) in Lerty
3. When the user responds, Lerty POSTs the response to your callback URL
4. Your workflow receives the callback and continues processing

Action Types

Each interactive message requires exactly one action element:

          curl -X POST "https://lerty.ai/api/v1/conversations/CONV_ID/interactive" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callback_url": "https://your-server.com/callback", "callback_id": "approval-001", "elements": [{"type": "header", "text": "Invoice Approval"}, {"type": "text", "text": "Invoice #1234 for $5,000"}, {"type": "boolean"}]}'

        

          curl -X POST "https://lerty.ai/api/v1/conversations/CONV_ID/interactive" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callback_url": "https://your-server.com/callback", "callback_id": "expense-001", "elements": [{"type": "header", "text": "Submit Expense"}, {"type": "fields", "submit_label": "Submit", "inputs": [{"name": "amount", "label": "Amount ($)", "input_type": "number", "required": true}]}]}'

        

          {
  "callback_id": "approval-001",
  "conversation_id": "conv-uuid",
  "message_id": "msg-uuid",
  "response_type": "boolean",
  "approved": true,
  "message": "Looks good",
  "responded_at": "2024-01-15T10:30:00Z",
  "responded_by": {
    "user_id": "user-uuid",
    "email": "user@example.com"
  }
}

        

          {
  "callback_id": "expense-001",
  "conversation_id": "conv-uuid",
  "response_type": "fields",
  "data": {
    "amount": 500,
    "category": "travel",
    "date": "2024-01-15"
  },
  "responded_at": "2024-01-15T10:30:00Z"
}

        

Typing Indicators

Show users that your agent is processing their message. Useful for longer-running workflows to keep users informed.

curl -X POST "https://lerty.ai/api/agents/AGENT_ID/callback" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_type": "typing",
    "conversation_id": "CONV_ID",
    "data": {
      "typing": true,
      "label": "Thinking...",
      "show_dots": true,
      "timeout": 60000
    }
  }'

Organization API

Manage your organization and team members programmatically. The organization is determined automatically from your API key.

curl -X GET "https://lerty.ai/api/v1/organization" \
  -H "Authorization: Bearer YOUR_API_KEY"

          {
  "organization": {
    "id": "org-uuid-here",
    "name": "My Company"
  }
}

        

          curl -X GET "https://lerty.ai/api/v1/organization/members" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

          {
  "members": [
    {"id": "user-uuid", "email": "owner@example.com", "role": "owner"},
    {"id": "user-uuid-2", "email": "member@example.com", "role": "member"}
  ]
}

        

          curl -X POST "https://lerty.ai/api/v1/organization/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "newuser@example.com"}'

        

          {
  "member": {
    "id": "user-uuid-new",
    "email": "newuser@example.com",
    "role": "member"
  }
}

        

          curl -X DELETE "https://lerty.ai/api/v1/organization/members/USER_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

Push Notifications

Send push notifications to users on the Lerty mobile app. Notify users of important events, approvals needed, or updates from your workflows.

          curl -X POST "https://lerty.ai/api/push/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "title": "New Message", "body": "You have a new message", "priority": "high"}'

        

{
  "success": true,
  "email": "user@example.com",
  "devices_succeeded": 2,
  "devices_failed": 0,
  "total_devices": 2
}

          curl -X POST "https://lerty.ai/api/push/send/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipients": ["user1@example.com", "user2@example.com"], "title": "Announcement", "body": "New features available"}'

        

          curl -X GET "https://lerty.ai/api/push/devices?email=user@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

Live Activities

iOS Live Activities display real-time updates on the Lock Screen and Dynamic Island. Perfect for order tracking, workflow progress, and time-sensitive notifications.

          curl -X POST "https://lerty.ai/api/push/live-activity/update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notification_id": "notif-123", "content_state": {"itemTitle": "Order Status", "status": "In Transit", "progressPercent": 75}}'

        

          {
  "success": true,
  "tokens_updated": 1,
  "notification_id": "notif-123"
}

        

          curl -X POST "https://lerty.ai/api/push/live-activity/update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notification_id": "notif-123", "event": "end", "content_state": {"itemTitle": "Complete", "status": "Delivered", "progressPercent": 100}}'

        

Databases

Databases are top-level containers for your data. Each database contains tables, which hold fields and entries.

Required permissions: data.databases:read for read operations, data.databases:write for create/update/delete.

          curl -X GET "https://lerty.ai/api/v1/databases" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

          {
  "data": [
    {
      "id": "db_abc123",
      "name": "My Database",
      "description": "Project tracker",
      "color": "#3B82F6",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

        

          curl -X POST "https://lerty.ai/api/v1/databases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Database", "description": "Project tracker", "color": "#3B82F6"}'

        

          {
  "data": {
    "id": "db_abc123",
    "name": "My Database",
    "description": "Project tracker",
    "color": "#3B82F6",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

        

          curl -X GET "https://lerty.ai/api/v1/databases/db_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

          curl -X PATCH "https://lerty.ai/api/v1/databases/db_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed Database"}'

        

          curl -X DELETE "https://lerty.ai/api/v1/databases/db_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

Tables

Tables live inside databases and define a schema through fields. Each table comes with default fields (text, select, date, checkbox) and 3 empty entries.

Required permissions: data.tables:read for read operations, data.tables:write for create/update/delete.

          curl -X GET "https://lerty.ai/api/v1/databases/db_abc123/tables" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

          {
  "data": [
    {
      "id": "tb_xyz789",
      "name": "Tasks",
      "fields": [
        { "id": "fd_aaa", "name": "Title", "type": "text", "config": {} },
        { "id": "fd_bbb", "name": "Status", "type": "select", "config": {
          "options": [
            { "id": "op_111", "label": "To do", "color": "gray" },
            { "id": "op_222", "label": "Done", "color": "green" }
          ]
        }}
      ],
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

        

          curl -X POST "https://lerty.ai/api/v1/databases/db_abc123/tables" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Tasks"}'

        

          curl -X DELETE "https://lerty.ai/api/v1/tables/tb_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

Fields

Fields define the columns/schema of a table. Supported types: text, number, select, date, checkbox, file, formula, url.

Required permissions: data.tables:read for listing, data.tables:write for create/update/delete.

          curl -X POST "https://lerty.ai/api/v1/tables/tb_xyz789/fields" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Priority", "type": "select", "config": {"options": [{"label": "High", "color": "red"}, {"label": "Low", "color": "gray"}]}}'

        

          {
  "data": {
    "id": "fd_ccc",
    "name": "Priority",
    "type": "select",
    "position": 2,
    "config": {
      "options": [
        { "id": "op_333", "label": "High", "color": "red" },
        { "id": "op_444", "label": "Low", "color": "gray" }
      ]
    },
    "created_at": "2025-01-15T10:30:00Z"
  }
}

        

          curl -X PATCH "https://lerty.ai/api/v1/fields/fd_ccc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Urgency"}'

        

          curl -X DELETE "https://lerty.ai/api/v1/fields/fd_ccc" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

Entries

Entries are rows in a table. Each entry has a values map where keys are field names or field IDs, and values are the cell data.

Required permissions: data.tables:read for read operations, data.tables:write for create/update/delete.

          curl -X GET "https://lerty.ai/api/v1/tables/tb_xyz789/entries?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

          {
  "data": [
    {
      "id": "en_abc123",
      "values": {
        "fd_aaa": "Build login page",
        "fd_bbb": "op_111"
      },
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

        

          curl -X POST "https://lerty.ai/api/v1/tables/tb_xyz789/entries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values": {"Title": "Build login page", "Status": "To do"}}'

        

          curl -X POST "https://lerty.ai/api/v1/tables/tb_xyz789/entries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values": {"fd_aaa": "Build login page", "fd_bbb": "op_111"}}'

        

          curl -X PATCH "https://lerty.ai/api/v1/entries/en_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values": {"Status": "Done"}}'

        

          curl -X POST "https://lerty.ai/api/v1/tables/tb_xyz789/entries/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": [{"field": "Status", "op": "is", "value": "To do"}], "sort": [{"field": "Title", "direction": "asc"}], "limit": 50}'

        

          curl -X POST "https://lerty.ai/api/v1/tables/tb_xyz789/entries/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operations": [{"action": "create", "values": {"Title": "New task"}}, {"action": "update", "id": "en_abc123", "values": {"Status": "Done"}}, {"action": "delete", "id": "en_def456"}]}'

        

          {
  "data": {
    "total": 3,
    "succeeded": 3,
    "failed": 0,
    "results": [...]
  }
}

        

          curl -X POST "https://lerty.ai/api/v1/tables/tb_xyz789/aggregate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"function": "sum", "field": "Amount"}'

        

          {
  "data": {
    "function": "count",
    "result": 42
  }
}

        

Entry Notes

Entry notes are rich-text documents stored as TipTap JSON. Each entry can have one notes document containing headings, paragraphs, lists, blockquotes, code blocks, and inline formatting.

Required permissions: data.tables:read for read, data.tables:write for update/append.

          curl -X GET "https://lerty.ai/api/v1/entries/en_abc123/notes" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

          {
  "data": {
    "entry_id": "en_abc123",
    "notes": {
      "type": "doc",
      "content": [
        {
          "type": "heading",
          "attrs": { "level": 1 },
          "content": [{ "type": "text", "text": "Meeting Notes" }]
        },
        {
          "type": "paragraph",
          "content": [
            { "type": "text", "text": "Discussed the " },
            { "type": "text", "marks": [{ "type": "bold" }], "text": "Q1 roadmap" },
            { "type": "text", "text": " with the team." }
          ]
        }
      ]
    },
    "has_notes": true
  }
}

        

          curl -X PATCH "https://lerty.ai/api/v1/entries/en_abc123/notes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notes": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Replaced notes content."}]}]}}'

        

          curl -X PATCH "https://lerty.ai/api/v1/entries/en_abc123/notes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notes": null}'

        

          curl -X POST "https://lerty.ai/api/v1/entries/en_abc123/notes/append" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": [{"type": "paragraph", "content": [{"type": "text", "text": "Appended a new paragraph."}]}]}'

        

          curl -X POST "https://lerty.ai/api/v1/entries/en_abc123/notes/append" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": [{"type": "heading", "attrs": {"level": 2}, "content": [{"type": "text", "text": "Update Log"}]}, {"type": "bulletList", "content": [{"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "marks": [{"type": "bold"}], "text": "Feb 17:"}, {"type": "text", "text": " API integration complete"}]}]}, {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "marks": [{"type": "bold"}], "text": "Feb 18:"}, {"type": "text", "text": " Deployed to production"}]}]}]}]}'

        

Files

Files are uploaded directly to S3 via presigned URLs — file data never passes through the Lerty server. Every file must be attached to an entry field of type file.

Required permissions: files:read for list/download, files:write + data.tables:write for upload/confirm/delete.

          curl -X GET "https://lerty.ai/api/v1/files?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

          {
  "data": [
    {
      "id": "file-uuid",
      "filename": "report.pdf",
      "content_type": "application/pdf",
      "size_bytes": 204800,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

        

          curl -X POST "https://lerty.ai/api/v1/files/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entry_id": "en_abc123", "field_id": "fd_file", "filename": "report.pdf", "content_type": "application/pdf", "size_bytes": 204800}'

        

          {
  "data": {
    "upload_url": "https://s3.amazonaws.com/bucket/key?X-Amz-Signature=...",
    "upload_token": "SFMyNTY...",
    "upload_headers": { "Content-Type": "application/pdf" },
    "expires_in": 3600
  }
}

        

          curl -X PUT "<upload_url from step 1>" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

        

          curl -X POST "https://lerty.ai/api/v1/files/confirm" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"upload_token": "SFMyNTY..."}'

        

          {
  "data": {
    "id": "file-uuid",
    "filename": "report.pdf",
    "content_type": "application/pdf",
    "size_bytes": 204800,
    "file_value": {
      "key": "org_.../files/abc.pdf",
      "bucket": "lerty-user-files",
      "filename": "report.pdf",
      "content_type": "application/pdf",
      "size": 204800,
      "file_id": "file-uuid",
      "uploaded_at": "2025-01-15T10:30:00Z"
    },
    "download_url": "https://s3.amazonaws.com/...",
    "download_url_expires_in": 3600,
    "entry": { "id": "en_abc123", "field_id": "fd_file" }
  }
}

        

          curl -X GET "https://lerty.ai/api/v1/files/FILE_ID/download" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

          {
  "data": {
    "download_url": "https://s3.amazonaws.com/...",
    "filename": "report.pdf",
    "content_type": "application/pdf",
    "size_bytes": 204800,
    "expires_in": 3600
  }
}

        

          curl -X DELETE "https://lerty.ai/api/v1/files/FILE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

        

Errors

Lerty uses standard HTTP status codes and returns JSON error responses.

Error Response Format

All errors return a structured JSON object with a code, human-readable message, and optional details.

        {
  "error": {
    "code": "authentication_required",
    "message": "Missing or invalid API key. Include your key as: Authorization: Bearer YOUR_API_KEY",
    "details": null
  }
}

      

Data API Error Codes

These error codes are specific to the Data API (entries, fields, tables).

Examples

        {
  "error": {
    "code": "field_not_found",
    "message": "Field 'Nonexistent' not found in this table.",
    "details": null
  }
}

      

        {
  "error": {
    "code": "validation_failed",
    "message": "Request body contains invalid fields.",
    "details": { "name": ["a field with this name already exists in this table"] }
  }
}

      

{
  "error": {
    "code": "plan_limit_reached",
    "message": "You have reached the maximum of 1000 entries on the Free plan. Upgrade to create more.",
    "details": null
  }
}

Plan Limits

API calls that exceed these limits return 402 with the plan_limit_reached code.

Getting Clients

If you've made it this far, you already know enough to sell AI agents. The rest is understanding your client's problems and matching them to solutions. This section shows you how to find the right clients, craft your offer, and close the deal.

Ideal Clients

Not all clients are equal. Use this framework to evaluate prospects before you invest time.

Cross Selling

Your existing clients are the easiest to sell to. They trust you and you already know their business.

Offer a free workflow audit or strategy session. Frame it as helping them find time or cost savings in their business. Most will say yes.

Questions to ask:

"What do you spend the first hour of your day doing?" "What tasks feel like busywork?" "Where do things get stuck waiting on you?" "What falls through the cracks?"

What to listen for:

Recurring tasks. Approval bottlenecks. Manual data entry. Anything they do daily or weekly that follows a pattern. That's your opportunity.

Outreach

If you're starting fresh, target industries with obvious pain points.

Step 1.) Find industries with built-in demand:

• Real estate: Leads, follow-ups, listing descriptions
• Home services: Quotes, scheduling, follow-ups
• Gyms and fitness: Membership follow-ups, class reminders
• Salons and spas: Booking confirmations, review requests
• Contractors: Project updates, quotes, invoicing

Get creative. Christmas light installers, float tank spas, pondscaping companies. The weirder the niche, the less competition. Long tail is untapped.

Step 2.) Research and identify tells:

Before you reach out, find proof they need help. Fill out their quote form and see if they follow up. Check their Google reviews for complaints about slow responses. See if they're hiring for admin or receptionist roles. These become your anchor points when you pitch.

Step 3.) Cold Looms:

Record a 2-minute Loom showing exactly what you found and a Lerty workflow that fixes it. "I filled out your quote form three days ago and never heard back. Here's what it would look like if you could respond in 30 seconds." Walk them through the agent, show the approval flow. Send the video in an email and offer a free workflow audit call.

Bonus - Upwork: Skip the research. People posting automation or AI jobs already have budget and intent to buy. Make sure their problem is a good fit, if it is, respond to their job listing.

Selling Agents

Use a two-call close. First call is a free strategy session where you assess their workflows and gather info. No pitching, just listening. Second call is where you present the proposal.

This works because you need real numbers to build a compelling proposal. Hourly rates, time spent, pain points. You can't guess that. The first call gives you everything you need to make the second call a no-brainer.

Before the second call, fill out the Proposal Generator below with what you learned. Their hourly costs, hours spent, the workflows you'll build. Have it ready so you can walk them through the numbers live and send the proposal before you get off the call.

Calculator

Formulas

Formula fields let you compute values from other fields in your table. They support arithmetic, comparisons, and built-in functions for strings, dates, and conditionals.

Syntax

Reference other fields by wrapping the field name in curly braces. Field names are case-sensitive.

Operators

Arithmetic operators for math and comparison operators for conditions.

Arithmetic

Comparison

Functions

Conditional

IF({Status} = "Done", "Complete", "Pending")

IF({Score} >= 90, "A", IF({Score} >= 80, "B", "C"))

String

CONCAT({First Name}, " ", {Last Name})

CONCAT("$", {Price})

Logic

IF(EMPTY({Notes}), "No notes", {Notes})

IF(EMPTY({Email}), "Missing", "Has email")

Date & Time — Current

Date & Time — Extract Components

Date & Time — Arithmetic

DATEADD({Start Date}, 7, "days")

DATEADD({Due Date}, 1, "months")

DATEADD(TODAY(), 14, "days")

DATESUBTRACT({Due Date}, 1, "months")

DATESUBTRACT({End Date}, 3, "weeks")

DATEDIFF({Start Date}, {End Date}, "days")

DATEDIFF({Created Date}, TODAY(), "weeks")

DATEDIFF(TODAY(), {Due Date}, "days")

Field Types

All field types can be referenced in formulas. Here's how each type resolves when used.

Examples

Common formula patterns you can use in your tables.

{Price} * {Quantity}

IF({Status} = "Done", "Complete", IF({Status} = "In progress", "Active", "Not started"))

DATEDIFF(TODAY(), {Due Date}, "days")

CONCAT({First Name}, " ", {Last Name})

IF(EMPTY({Email}), "Missing email", {Email})

IF({Score} >= 90, "A", IF({Score} >= 80, "B", IF({Score} >= 70, "C", "F")))

DATEADD({Close Date}, 14, "days")

DATEDIFF({created_date}, TODAY(), "days")

MCP Server

Lerty exposes a Model Context Protocol (MCP) server so any MCP-compatible client (Claude Desktop, Cursor, Windsurf, custom agents) can read and write your Lerty data using structured tools. The server uses the Streamable HTTP transport and authenticates with the same API keys as the REST API.

Connection

Point your MCP client at the Streamable HTTP endpoint. Authentication is via Bearer token using your Lerty API key.

Database Tools

Databases are the top-level containers in Lerty's data hierarchy. Each database contains tables, which contain fields and entries.

Table Tools

Tables live inside databases and hold fields (columns) and entries (rows).

Field Tools

Fields define the columns in a table. Supported types: text, number, select, multi_select, date, checkbox, file, relation, user, formula, rollup.

Entry Tools

Entries are the rows in a table. Values are keyed by field display ID (fd_xxx) or field name. Select/multi_select values accept option IDs (op_xxx) or human-readable labels.

Notes Tools

Each entry can have a rich-text notes document stored as TipTap JSON.