> ## Documentation Index
> Fetch the complete documentation index at: https://www.forager.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Forager is a REST API for B2B people, company and job post data: contact lookups (phone numbers, personal emails, work emails), person, company and job post search, and bulk data feeds.
> Server: https://api-v2.forager.ai. Send the API key in the X-API-KEY header. Most paths include {account_id}. Read FORAGER_API_KEY and FORAGER_ACCOUNT_ID from the environment; never put the key in client-side code, logs or prompts.
> To add Forager to a project, follow https://www.forager.ai/docs/guides/agent-quickstart.md. To pick an endpoint, read https://www.forager.ai/docs/guides/choose-an-endpoint.md. For end-to-end builds, see https://www.forager.ai/docs/recipes/overview.md.
> Most requests spend credits. Do not guess costs; use https://www.forager.ai/docs/api-overview/credit-pricing.md and ask the user before spending credits.
> Use only endpoints and fields defined in https://www.forager.ai/docs/openapi.yaml. Forager has no MCP server for the API yet; the /mcp endpoint on this site searches the documentation only.

# Agent quickstart

> Steps a coding agent follows to add the Forager API to a project: get the key from the user, pick the endpoint, write a server-side client, test.

![Agent quickstart flow: a setup prompt sends a coding agent to the Forager docs as Markdown, then into your project](https://mintcdn.com/forager/EGsWCxLOYv1Cb__c/images/illustrations/coding-agent-setup-prompt-flow.svg?fit=max\&auto=format\&n=EGsWCxLOYv1Cb__c\&q=85\&s=9cb64a32085d08a6864fc7580eec532b)

This page is written for coding agents such as Claude Code, Codex or Cursor. To use it, paste this prompt into your agent:

```text Setup prompt theme={"theme":{"light":"github-light","dark":"github-dark"}}
Read https://www.forager.ai/docs/guides/agent-quickstart.md and follow it to add the Forager API to this project. Keep my API key server-side in FORAGER_API_KEY and FORAGER_ACCOUNT_ID.
```

## Instructions for the agent

Follow these steps in order. Ask the user before any step that spends credits.

**1. Get the credentials from the user**

You can't create a Forager account or API key yourself. Ask the user to:

1. Sign up at [app.forager.ai](https://app.forager.ai/sign-up), or sign in.
2. Create a key on the [API](https://app.forager.ai/keys) page.
3. Copy the Account ID from [My Account](https://app.forager.ai/profile).

Then:

* Store them as `FORAGER_API_KEY` and `FORAGER_ACCOUNT_ID` in the project's existing secrets setup, such as `.env` (gitignored) or the platform's secret store.
* Never write the key into source files, logs, prompts or client-side code.

**2. Learn the API**

* Read the [Forager API skill](https://www.forager.ai/docs/skill.md): endpoints, auth, costs and a pre-flight checklist.
* Use [Choose the right endpoint](https://www.forager.ai/docs/guides/choose-an-endpoint.md) to map what the user has to the endpoint they need.
* The full spec is [openapi.yaml](https://www.forager.ai/docs/openapi.yaml), and every page is available as Markdown by adding `.md` to its URL.

The essentials:

* Server `https://api-v2.forager.ai`.
* Send the key in the `X-API-KEY` header.
* Most paths include `{account_id}`.

**3. Write a small server-side client**

Follow the project's existing conventions for HTTP calls, configuration and errors. The client should:

* Read `FORAGER_API_KEY` and `FORAGER_ACCOUNT_ID` from the environment.
* Send JSON bodies with `Content-Type: application/json`.
* Treat `403` as a credentials problem and surface it clearly.
* Back off and retry on `429`, as described in [API errors and rate limits](https://www.forager.ai/docs/errors-and-rate-limits.md).
* Handle an empty result as "not found", not as an error.

If the project matches a recipe, follow the recipe instead. See [Recipes](https://www.forager.ai/docs/recipes/overview.md); each starts with its own prompt.

**4. Check the cost, then test one call**

Most lookups spend credits; see [credits and pricing](https://www.forager.ai/docs/api-overview/credit-pricing.md). A phone number lookup costs 15 credits per lookup.

* Tell the user what a test call costs and get a yes before you send it.
* Prefer one request with a known LinkedIn public identifier the user gives you.
* Never loop over real data during setup.

**5. Add tests and document the setup**

* Add tests that mock the HTTP layer. Tests must not call the live API or spend credits.
* Document the two environment variables and how to try the integration.

## Rules for agents

![Coding agent setup asks the user to approve one test call before spending Forager credits](https://mintcdn.com/forager/EGsWCxLOYv1Cb__c/images/illustrations/agent-quickstart-credit-approval-step.svg?fit=max\&auto=format\&n=EGsWCxLOYv1Cb__c\&q=85\&s=698a71db34cb22b5ff2371cdab628612)

* Don't guess credit costs, endpoints or field names. Use [credit pricing](https://www.forager.ai/docs/api-overview/credit-pricing.md) and the [API reference](https://www.forager.ai/docs/openapi.md).
* Don't call the API from browser code; the key would be exposed.
* Report bad data with the [feedback endpoints](https://www.forager.ai/docs/guides/report-bad-data.md) instead of retrying the same lookup.
* The docs MCP server at `/mcp` searches these docs only. It does not call the Forager API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.