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.

Quick start

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.

Actions

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.

GroupActionsNotes
Findfind_person, search_options, count_companies, search_people, load_companiesfind_person and counts are free; a search writes a new list
Checkcheck_records, verify_email100+ checks on the records you send, nothing stored
Enrichenrich_records, get_jobWork e-mail, mobile, job title, LinkedIn, company data; charged per hit
Lists · Read + checkdescribe_list, query_records, check_list34 filter conditions, e.g. c_level_executive, disposable_email, fuzzy_match
Lists · Editadd_records, update_records, mark_records, fix_list, copy_recordsadd_records up to 1,000 per call; update_records supports only_empty
Lists · Fullenrich_records with list_id, derive_column, send_to_pipelinederive_column fills a column with AI, paid by use
Permissions

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.
Costs

What a call costs.

1 credit is $0.035 with Pro, $0.06 on Basic. Reading, checks and fixes are free.

OperationCredits
find_person, check_records, count_companies, search_optionsfree
describe_list, query_records, check_list, fix_list and the other list toolsfree
search_people (per page of up to 25 people)2
load_companies (per company)0.25
verify_email (per address)0.3
enrich_recordsper field found, estimate: true first
derive_columnAI 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.