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"}'

        

          {
  "success": true,
  "conversation": {
    "id": "conv-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}}'

        

Errors

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

Error Response Format

{
  "error": "unauthorized",
  "message": "Invalid or missing API key",
  "success": false
}

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