# Using the API from an AI agent

An agent can learn the whole API from [/llms-full.txt](https://installgraph.com/llms-full.txt) or [/openapi.json](https://installgraph.com/openapi.json), get a key with one POST, and spend safely because counts are **free** and every response reports the remaining balance.

## Point the agent at the docs

| Resource | Use |
| --- | --- |
| [/llms.txt](https://installgraph.com/llms.txt) | A short index of the site and docs |
| [/llms-full.txt](https://installgraph.com/llms-full.txt) | Every docs page in one Markdown file: paste or fetch into context |
| [/openapi.json](https://installgraph.com/openapi.json) | OpenAPI 3.1 with examples: generate tools or a client from it |
| `/docs/….md` | Any single page as Markdown (add `.md` to its URL) |
| [`GET /v1/pricing`](https://installgraph.com/docs/reference/get-pricing.md) | Live prices as JSON, no key |

## A safe loop

1. **Know the prices.** `GET /v1/pricing` (no key) rather than prices from memory.
2. **Get a key from the person.** Accounts are made in the browser: they sign up at installgraph.com/login and copy the key from their dashboard. Never ask for it in a chat log; read it from an environment variable.
3. **Count first.** [`GET /v1/apps/{slug}/companies/count`](https://installgraph.com/docs/reference/count-app-companies.md) is free. The count is the most a full pull can cost.
4. **Confirm big spends.** If the count is more than the person asked for, or more than `meta.creditsRemaining`, ask before pulling.
5. **Pull with `limit`** set to the rows you need, and read `meta.creditsRemaining` after each page.
6. **On `402`**, stop. Show the person `error.offers.pack.buyUrl`, or, only if they have turned on agent purchases, call [`POST /v1/billing/purchase`](https://installgraph.com/docs/reference/agent-purchase.md).
7. **Branch on `error.code`**, never on `message`. Wait `Retry-After` seconds on `429`. See [Errors](https://installgraph.com/docs/errors.md).

## Instructions to give an agent

```text
You can call the Installgraph API (base URL https://api.installgraph.com) with the key in INSTALLGRAPH_API_KEY,
sent as "Authorization: Bearer <key>". Docs: https://installgraph.com/llms-full.txt
1 credit unlocks 1 store. Counts are free: always call /v1/apps/{slug}/companies/count before
/v1/apps/{slug}/companies, and ask me before any pull over 100 credits. Use limit to cap each page.
Report meta.creditsRemaining when you finish. On a 402, stop and show me error.offers.pack.buyUrl.
Never put the key in a URL, a file you write, or your reply.
```

## Agent purchases

Off by default. The account owner turns them on at [installgraph.com/account](https://installgraph.com/account) and sets a per-purchase and a 30-day limit. Then [`POST /v1/billing/purchase`](https://installgraph.com/docs/reference/agent-purchase.md) with `{"pack": "starter"}` buys on the card saved at the account's first checkout. Outside the owner's limits it answers `403 purchase_not_allowed`; past $1,000 in 30 days, `402 spend_cap_reached`.