Agent API
One connection. Every action your list offers.
REST and MCP on the same token. A GET returns columns, types, allowed actions and filter conditions, so an agent works with the real structure instead of documentation.
Self-describing
GET the connection and receive schema, actions, conditions and limits.
MCP & REST
Claude, ChatGPT or any MCP client on /mcp, any HTTP client on /d.
Permissions
Visible columns, writable fields, allowed actions and limits, per connection.
Three calls.
Create a connection on a list, copy the token, and the endpoint tells your agent the rest.
# 1. Discover what the connection exposes
curl https://listplus.ai/d/{token}
# 2. Query records with a condition-based filter
curl -X POST https://listplus.ai/d/{token} \
-H "Content-Type: application/json" \
-d '{ "action": "query",
"filter": { "email": { "condition": "disposable_email" } },
"limit": 50 }'
# 3. Fill empty job titles without touching existing values
curl -X POST https://listplus.ai/d/{token} \
-H "Content-Type: application/json" \
-d '{ "action": "update", "only_empty": true, "dry_run": true,
"records": [ { "id": "ar_000042", "job_title": "Head of RevOps" } ] }'Every call is logged with action, rows, credits and duration.
What the endpoint exposes.
Grouped by what they do. Each can be allowed or denied per connection.
| Group | Actions | Notes |
|---|---|---|
| Read | query, count, find, column_summary, credit_balance | 34 filter conditions, e.g. c_level_executive, disposable_email, fuzzy_match |
| Write | add_records, update, set_tags, set_status, send_to_pipeline, ignore, restore, create_columns | add_records up to 1,000 per call; update supports dry_run and only_empty |
| Quality | run_checks, fix_check, clean_values, dedup_merge, derive | run_checks and clean_values are free; derive fills a column with AI |
| Enrich | enrich (company, contact, person_lookup) | E-mail and phone lookups: credits only when found |
| Research | google_search, website_scrape, hackernews_search, company_lookup, twitter_search, reddit_search | Google, scrape and Hacker News are free; the rest per call |
The connection decides, not the prompt.
Settings per connection. Presets: Read Only, Data Assistant, Enrichment, Data Collector, Full Access, Custom.
- hiddenColumns, allowedSublists
- What the agent can read. Hidden columns never leave ListPlus.
- writableColumns, onlyFillEmpty
- What the agent may change, and whether populated values are protected.
- maxEnrichPerRequest, rateLimitPerMinute, expiresAt
- Volume per request, requests per minute (default 60) and an expiry date.
What a call costs.
1 credit is $0.035 with Pro or Premium, $0.06 on Basic. Reads, checks and fixes are free.
| Operation | Credits |
|---|---|
| query, count, find, run_checks, fix_check, clean_values | free |
| google_search, website_scrape, hackernews_search | free |
| company_lookup | 0.25 |
| twitter_search (per 100 tweets) | 3 |
| reddit_search | 10 |
| enrich: company | 0.25 |
| enrich: contact (Prospeo / FullEnrich) | 2 / 4 |
| enrich: person_lookup (name + company) | 6 |
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. The GET response documents the connection.
How does authentication work?
The token in the URL identifies the connection and its permissions. Create one per list and per agent, set an expiry, and deactivate it when the job is done.
Can I test writes safely?
Yes. update accepts dry_run, which returns what would change without writing. only_empty protects populated fields.
Which plan includes the API?
Premium. Research, enrichment and verification follow their credit rules; reads, checks and fixes are free.
Start with anything. End with contacts that are ready.
Try the sample list or bring your own starting point.