Skip to main content

Use Icypeas with AI agents

These docs are built to be read by machines as well as humans. Give your AI assistant one link and it can write a working Icypeas integration for you, even if you've never written code.

The fastest way: one prompt​

Paste this into ChatGPT, Claude, Cursor, Copilot or any assistant that can browse the web:

Prompt
Read https://api-doc.icypeas.com/llms-full.txt.
Then write a script that reads names and companies from my file people.csv,
finds each person's professional email with the Icypeas API and saves the
results to results.csv. Ask me for anything you need, like my API key.

Change the second part to whatever you need: a Google Sheets script, a Make scenario, a Python function, a CRM integration…

On any page

Use the Copy page button at the top of every page to copy it as clean Markdown, or open it straight in ChatGPT or Claude from the menu next to it.

Machine-readable resources​

ResourceURLUse it for
llms.txt/llms.txtShort index of every page, with a summary of the key rules. Follows the llmstxt.org standard.
llms-full.txt/llms-full.txtThe whole documentation in a single Markdown file. Best for loading everything into the context at once.
Markdown pagesAdd .md to any URL, for example /reference/email-search.mdOne page at a time, without the website around it.
OpenAPI 3.1/openapi.jsonImport into Postman, Insomnia, Bruno, or give it to agent frameworks that generate tools from OpenAPI.

Rules your agent must know​

If your agent only reads one thing, make it this:

  1. Base URL: https://app.icypeas.com/api.
  2. Headers: Authorization: <API key> (no Bearer) and Content-Type: application/json.
  3. Searches are asynchronous. POST /email-search returns item._id. Read the result with POST /bulk-single-searchs/read and {"id": "<_id>"} until status is not NONE, SCHEDULED or IN_PROGRESS. Wait at least 3 seconds between reads.
  4. Check success. Bad input returns HTTP 200 with "success": false and a validationErrors array.
  5. Respect the rate limits: back off and retry on HTTP 429.
  6. Use bulk search for more than a handful of items.

Import into Postman in 30 seconds​

  1. In Postman, click Import.
  2. Paste https://api-doc.icypeas.com/openapi.json and confirm.
  3. In the generated collection, set the Authorization header (or the collection's API key auth) to your API key.

Every endpoint is now ready to try, with example bodies.

Keep your key out of prompts​

warning

Don't paste your API key into a chat you share. Ask the assistant to read it from an environment variable (for example ICYPEAS_API_KEY) or a settings cell, and set it yourself.