Agent API reference · REST + MCP
One connection. Your workspace and the lists you share.
REST and MCP with the same actions. GET /a returns every action with its price, the free limits and the rules, so an agent knows what it may do and what it costs before it starts.
Self-describing
GET /a for the guide; describe_list for the columns, statuses and rights of a shared list.
MCP & REST
Claude, ChatGPT or any MCP client on /mcp, any HTTP client on /a/v1/{action}.
Permissions
Lists shared per connection as Read + check, Edit or Full, plus a credit budget per day.
Four calls.
Create a key on the Your AI page, or let Claude, ChatGPT or Claude Code sign in. The guide tells your agent the rest.
# 1. Read the guide: every action, its price and the rules
curl https://listplus.ai/a
# 2. Check records for errors (free, nothing is stored)
curl -X POST https://listplus.ai/a/v1/check_records \
-H "Authorization: Bearer lpk_…" \
-H "Content-Type: application/json" \
-d '{ "records": [ { "first_name": "MAYA", "last_name": "Chen",
"email": "maya.chen@gmial.com", "company_name": "Northstar Labs" } ] }'
# 3. Price the missing job titles before anything runs
curl -X POST https://listplus.ai/a/v1/enrich_records \
-H "Authorization: Bearer lpk_…" \
-H "Content-Type: application/json" \
-d '{ "records": [ { "first_name": "Maya", "last_name": "Chen",
"company_name": "Northstar Labs" } ],
"fields": ["job_title"], "estimate": true }'
# 4. Add a record to a list you shared with this connection
curl -X POST https://listplus.ai/a/v1/add_records \
-H "Authorization: Bearer lpk_…" \
-H "Content-Type: application/json" \
-d '{ "list_id": "ws_…", "records": [ { "first_name": "Maya",
"last_name": "Chen", "company_name": "Northstar Labs" } ] }'Every call is logged on the Your AI page with its action and credits.
What the connection offers.
Workspace actions work without a list. List tools work on the lists you share, as far as the list’s access allows.
| Group | Actions | Notes |
|---|---|---|
| Find | find_person, search_options, count_companies, search_people, load_companies | find_person and counts are free; a search writes a new list |
| Check | check_records, verify_email | 100+ checks on the records you send, nothing stored |
| Enrich | enrich_records, get_job | Work e-mail, mobile, job title, LinkedIn, company data; charged per hit |
| Lists · Read + check | describe_list, query_records, check_list | 34 filter conditions, e.g. c_level_executive, disposable_email, fuzzy_match |
| Lists · Edit | add_records, update_records, mark_records, fix_list, copy_records | add_records up to 1,000 per call; update_records supports only_empty |
| Lists · Full | enrich_records with list_id, derive_column, send_to_pipeline | derive_column fills a column with AI, paid by use |
The connection decides, not the prompt.
Each list is shared per connection as Read + check, Edit or Full. Records are never deleted through an agent: hiding them is the most — a hidden record leaves the normal flow (no checks, rules, enrichment or sync) until it is shown again.
- Hidden columns, sublists
- What the agent can read on a list. Hidden columns never leave ListPlus.
- Writable columns, only fill empty
- What the agent may change, and whether populated values are protected.
- Day budget, expiry
- Credits the connection may spend per day and an optional expiry date. Revoking stops its running jobs.
What a call costs.
1 credit is $0.035 with Pro, $0.06 on Basic. Reading, checks and fixes are free.
| Operation | Credits |
|---|---|
| find_person, check_records, count_companies, search_options | free |
| describe_list, query_records, check_list, fix_list and the other list tools | free |
| search_people (per page of up to 25 people) | 2 |
| load_companies (per company) | 0.25 |
| verify_email (per address) | 0.3 |
| enrich_records | per field found, estimate: true first |
| derive_column | AI by use |
Agent API access is included in every plan — even the free one.
Good to know.
Do I need an SDK?
No. The API is plain HTTP with JSON. curl, Python, JavaScript or any MCP client work. GET /a documents every action.
How does authentication work?
Claude, ChatGPT and Claude Code sign in with your ListPlus account. Other clients send a key as Authorization: Bearer lpk_…. A workspace owner or admin connects an AI on the Your AI page, sets its day budget and an expiry, and revokes it when the job is done.
Can I see what a job costs first?
Yes. enrich_records, search_people and load_companies take estimate: true and return the price without running. only_empty protects populated fields when your agent updates a list.
Which plan includes the API?
Every plan, Basic included. Searches, enrichment and verification follow their credit rules; reading, checks and fixes are free.
Start with anything. End with contacts that are ready.
Try the sample list or bring your own starting point.