Conventions
Every planned Leadee API response follows the same shape: a data envelope, cursor-based pagination, HTTP status codes for errors, and rate-limit headers tied to your plan tier. This page documents those conventions so client code written against the v1 API keeps working as new fields get added.
Updated
Success envelopes
A single resource:
{ "data": { "id": "...", "...": "..." } }A collection, paginated:
{
"data": [],
"meta": { "next_cursor": "...", "has_more": false }
}How will pagination work?
Lists will be cursor-based, the same strategy the JSON:API specification documents for a page[cursor]-style parameter. Walk forward by following meta.next_cursor until meta.has_more is false.
| Parameter | Default | Notes |
|---|---|---|
limit | 20 | Maximum 100 |
cursor | none | Opaque value from meta.next_cursor |
Errors
Branch on the HTTP status, per the status-code definitions in RFC 9110.
| Status | Meaning |
|---|---|
| 400 | Validation failed, or a plan limit was reached (for example, exceeding your plan's tracked-prompt count) |
| 401 | Missing or invalid API key |
| 402 | Plan capability not available on your current tier |
| 403 | Authenticated but not permitted |
| 404 | Not found |
| 429 | Rate limited |
| 5xx | Internal error |
Rate limits
Rate limits will be tiered by plan, matching the monthly API/MCP call allowance published on the pricing page. X-RateLimit-Limit and X-RateLimit-Remaining headers are planned on every response.
Versioning
v1 is the only planned version. New response fields will be additive; clients should ignore fields they do not recognize.
Related
- Documentation home for the full list of planned API modules.
- Authentication for how requests will be authenticated.
Conventions questions
How will pagination work in the Leadee API?
Lists will be cursor-based: walk forward by following meta.next_cursor in each response until meta.has_more is false. The default page size will be 20 items, with a maximum of 100.
Will the Leadee API have rate limits?
Yes, tiered by plan and matching the monthly API/MCP call allowance on the pricing page. X-RateLimit-Limit and X-RateLimit-Remaining headers are planned on every response so clients can back off before hitting a 429.
Which HTTP status code means I hit a plan limit?
402. A 400 means the request itself failed validation; a 402 means the request was valid but exceeded a plan limit, such as your tracked-prompt count — branch on the status code, not just the presence of an error.
Can GEO guarantee results?
No. AI answer engines change their output frequently, and no vendor — including Leadee — can guarantee a ranking or a mention. Leadee publishes confidence intervals on every metric so you can see how much a result can vary run to run.
How does Leadee measure AI visibility?
Leadee runs your prompt set against each AI engine on a weekly to daily schedule, depending on plan, through official vendor APIs (OpenAI, Gemini, Perplexity, Anthropic, DataForSEO) — never by scraping consumer chat interfaces — and reports mention rate, citation rate, average position, share of voice and sentiment with a 95% confidence interval.
Who do I talk to?
Email support@leadee.ai or use Talk to an expert at https://leadee.ai/contact-sales — the Netbase JSC team behind Leadee replies by email or WhatsApp — or WhatsApp the CEO directly at https://wa.me/84937869689.