Skip to main content
Every endpoint of the Starleads public API is documented in this section, grouped by resource.
Base URL: https://api.starleads.co — every request requires the X-Api-Key header.

​
Where to start

Most integrations only need the campaign endpoints: create a campaign, push your prospects into it, then receive the results via webhook.

Campaigns

List and create the campaigns your AI agents run.

Campaign Items

Add, retrieve and remove the prospects of a campaign.

Campaign Fields

Read the custom fields expected in an item’s databag.

Agents

Read and update an agent’s prompt, and connect it to a knowledge base.

​
Knowledge base (RAG)

Optional. Use these endpoints only if you want your agents to answer from your own documents. Start with the Knowledge Base guide rather than the raw endpoints — the objects have to be created in order.

Datasets

Containers holding the documents your agents draw answers from.

Documents

Upload, parse and manage the files inside a dataset.

Knowledge Base Chats

The retrieval configuration an agent is connected to.

Knowledge Graph

Extract entities and relations from a dataset.

​
Billing & reporting

Track what your company consumes and inspect your contract. All figures are company-wide and derived from your API key — no company identifier is passed. Start with the Track Consumption guide to build balance monitoring end to end.
These endpoints expose your company’s billing data to any holder of the API key: balance, breakdown, contract and ledger. Review where your keys are distributed — see the Authentication guide.

Current Consumption

The credit balance for the current billing period: included, consumed and remaining credits.

Consumption Breakdown

Consumption split by channel, month and agent over a date range.

Consumption Transactions

The credit ledger, one entry per line, paginated.

Subscription

Your plan, status, active features and effective limits — no pricing.

​
Conventions

Authentication — pass your key in the X-Api-Key header on every call. See the Authentication guide to retrieve it. Pagination — list endpoints accept pageNumber (starts at 1) and pageSize (1 to 100, default 50). Responses carry data, total, pageNumber and pageSize. Errors — failures return an RFC 7807 problem object.
A resource owned by another company answers 404, not 403, so the API never discloses that it exists.
502 and 504 mean the failure is on our side, not in your request — retry rather than change your parameters. A 4xx means the opposite.
Some 400 responses carry an extra errors object naming the offending fields; this happens when a parameter fails validation before reaching the endpoint. It is an RFC 7807 extension member, so client code reading type, title, status and detail works either way. Rate limiting — responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Heavy operations (uploads, parsing, knowledge graph builds) have tighter limits than plain CRUD calls. Contract evolution — the public API has no route versioning. To keep your integrations stable, we follow one rule:
  • Adding a field to a response is a non-breaking change and may happen at any time, without notice. Write your clients to ignore unknown fields rather than reject them.
  • Removing a field, or changing the meaning of an existing field, is a breaking change. It will never be done in place on an existing route — it requires a new route instead. The old route keeps its exact contract.
Parse responses tolerantly: a new field appearing tomorrow must not break your integration. A field you rely on today will keep both its name and its meaning for the lifetime of the route.