API reference
The read-only REST API behind the Zapier and Make apps: authentication with API keys, errors, and the leads, conversations, projects and account endpoints.
Larvabot has a small, read-only REST API for getting your leads and conversations out: into a CRM, a spreadsheet, or your own code. The Larvabot apps for Zapier and Make are built on it.
Every endpoint is a GET that returns JSON. Nothing in Larvabot can be changed through the API.
#Base URL
https://app.larvabot.com/api/v1#Authentication
Create an API key in Larvabot under Settings → Integrations → API keys. Keys start with lb_ and are shown once, when you create them. Send the key with every request, in either header:
Authorization: Bearer lb_your_key
X-API-Key: lb_your_keyA key reads only the projects of the account that created it. Revoke a key on the same page and it stops working straight away. Larvabot stores only a fingerprint of each key, so a lost key can't be shown again: revoke it and make a new one.
curl https://app.larvabot.com/api/v1/me -H "Authorization: Bearer lb_your_key"#Errors
Errors come back with an HTTP status and a JSON body with one error field, written to be shown to people as is:
{ "error": "This API key isn't valid. It may have been revoked." }| Status | When |
|---|---|
400 | A parameter has a value the endpoint doesn't accept, e.g. an unknown event |
401 | The key is missing, wrong or revoked |
402 | The account's plan isn't active (it works again once a plan is) |
#Lists, limits and polling
List endpoints return a plain JSON array, newest first. limit sets how many items come back: 100 by default, at most 500. There are no pages: to keep in sync, poll every few minutes and keep the items whose id you haven't seen yet, which is what Zapier and Make do. Dates are ISO 8601 in UTC (2026-10-02T14:05:00.000Z); a date that hasn't happened yet is null.
Every list endpoint takes an optional project parameter: a project ID from /projects. Leave it out to get all your projects.
#GET /me
The account the key belongs to. Use it to check a key works.
{ "id": 42, "email": "sam@example.com", "name": "Sam Rivera" }#GET /projects
Your projects. id is what the other endpoints take as project.
[{ "id": "acme-djs", "name": "Acme DJs", "domain": "acmedjs.com" }]#GET /leads
Businesses found for email outreach.
| Parameter | Values |
|---|---|
event | found (default): scored as a fit, newest found first. contacted: the first email has been sent, newest first. replied: they replied, newest reply first |
project | A project ID (optional) |
limit | 1 to 500, default 100 |
curl "https://app.larvabot.com/api/v1/leads?event=replied&limit=20" -H "Authorization: Bearer lb_your_key"[
{
"id": 1234,
"name": "Sam Rivera",
"email": "sam@riverastudio.com",
"company": "Rivera Studio",
"website": "https://riverastudio.com",
"domain": "riverastudio.com",
"page_url": "https://riverastudio.com/about",
"contact_form_url": "",
"socials": "https://www.linkedin.com/company/riverastudio",
"offering": "wedding photography",
"location": "Austin, Texas",
"fit_score": 86,
"fit_reason": "Books weddings in Austin and refers couples to DJs.",
"stage": "replied",
"project": "Acme DJs",
"project_domain": "acmedjs.com",
"campaign": "Austin wedding vendors",
"found_at": "2026-10-01T09:30:00.000Z",
"contacted_at": "2026-10-02T14:05:00.000Z",
"replied_at": "2026-10-03T08:12:00.000Z",
"dashboard_url": "https://app.larvabot.com/p/acme-djs/emails"
}
]| Field | Type | What it is |
|---|---|---|
id | number | The lead's ID, stable for the lead's lifetime |
name, email | string | The contact Larvabot found (empty when none was found) |
company, website, domain | string | The business and its site |
page_url | string | The page that made them worth contacting |
contact_form_url, socials | string | Other ways to reach them; socials is comma-separated |
offering, location | string | What they sell and where, when their site says |
fit_score | number | How well they match the project, 0 to 100 |
fit_reason | string | Why they fit |
stage | string | qualified, contact, drafted, approved, sent, replied or linked |
project, project_domain, campaign | string | Where the lead came from |
found_at, contacted_at, replied_at | date or null | When each happened |
dashboard_url | string | The lead's project in Larvabot |
#GET /conversations
Posts where someone asks for what you sell, scored 50 or more for relevance, newest first.
| Parameter | Values |
|---|---|
project | A project ID (optional) |
limit | 1 to 500, default 100 |
[
{
"id": 987,
"platform": "reddit",
"author": "austin_bride_2026",
"title": "Looking for a DJ for our wedding after-party on Dec 4",
"url": "https://www.reddit.com/r/Austin/comments/abc123/",
"excerpt": "Any recommendations? Budget is flexible.",
"relevance": 91,
"intent": "asking",
"why": "Asks for a wedding DJ in Austin, which is exactly what you offer.",
"suggested_reply": "Congrats! I run a small DJ outfit in Austin...",
"status": "new",
"project": "Acme DJs",
"project_domain": "acmedjs.com",
"posted_at": "2026-10-03T18:40:00.000Z",
"found_at": "2026-10-03T19:00:00.000Z",
"dashboard_url": "https://app.larvabot.com/p/acme-djs/conversations"
}
]| Field | Type | What it is |
|---|---|---|
id | number | The conversation's ID |
platform | string | Where it was posted: reddit, threads, x, facebook, linkedin, hackernews, forum, web and others |
author, title, url | string | The post |
excerpt | string | The start of the post, up to 500 characters |
relevance | number | How closely it matches what you sell, 0 to 100 |
intent | string | asking, alternative, complaint, problem, mention or other |
why | string | Why it fits |
suggested_reply | string | The reply Larvabot drafted for you |
status | string | new, posted or ignored |
project, project_domain | string | Which project found it |
posted_at, found_at | date or null | When it was posted and when Larvabot found it |
dashboard_url | string | The project's Conversations tab |
#CSV instead
Prefer a spreadsheet? Settings → Integrations → Download as CSV gives the same fields for leads and conversations, without an API key. Send leads to your CRM