# Agent instructions for Veezee

Non-obvious rules only. Marketing lives at https://veezee.io/, not here.

## Getting a key

- Call `provision` first. No signup, no card, no key needed to call it.
- The response's `api_key` is shown exactly once. Store it yourself; Veezee cannot show it again.
- Over MCP, later calls in the same session authenticate automatically once you've provisioned.
- Over REST, send `Authorization: Bearer <api_key>` on every call.
- Per-client install snippets (Claude Code, Cursor, VS Code, Codex CLI, and more): https://veezee.io/docs/clients

## Worked recipes

- Candidate sourcing, prospect enrichment, company research, with per-step credit costs: https://veezee.io/use-cases/candidate-sourcing, https://veezee.io/use-cases/prospect-enrichment, https://veezee.io/use-cases/company-research

## Idempotency

- Every metered REST call (GET included; our GETs charge credits) requires an `Idempotency-Key` header.
- Reuse the SAME key only when retrying the SAME call after a failure or timeout. A new call needs a new key.
- Reusing a key with different arguments is an error, not a merge.

## Cost control

- `search_people`: one call at `limit=30` costs less than three calls at `limit=10`. A cursor page is priced fresh by its own limit, so prefer one large limit over paging.
- `get_profile`: the first 2 sections (about, experience, education, skills) are free with the base fetch; each section past 2 costs 2 credits, up to 4 total.
- `freshness: "realtime"` adds 2 credits, refunded automatically if the live fetch falls back to cached data. Default (`recent`) is free and usually a few hours old.
- Set `max_credits` on a call to cap its own spend; if the quote would exceed it, nothing is charged.

## Results you cannot fetch

- `search_people` results with `is_anonymous: true` are private profiles. `get_profile` cannot dereference them: treat the match as confirmed and stop, don't retry.

## Identifiers

- `get_profile` / `get_company` / `get_posts` accept a URL, a slug, or a URN directly. Only call `resolve_url` first when the URL is dirty or ambiguous; resolving a clean identifier just spends 2 credits for nothing.
- `search_people`'s `current_company` / `past_company` filters accept a plain company name; you don't need the id or URN first.

## Trial limits

- 500 credits, 1 concurrent call, 20 calls/minute, search capped at 10 results/call, 5 realtime fetches total, for the life of the trial key.
- `get_usage` is free and exempt from the rate limit: call it to check balance before a batch, not after INSUFFICIENT_CREDITS.

## When payment blocks you

- `provision` and `get_usage` return an account-bound `upgrade_url`; errors a payment can fix (INSUFFICIENT_CREDITS, BUDGET_EXHAUSTED, TRIAL_CAP_EXCEEDED) carry it too. Give that link to your human: purchases credit your account directly with no login, your key keeps working, and you continue after payment.
- Retrying INSUFFICIENT_CREDITS or BUDGET_EXHAUSTED unchanged does nothing; the balance only moves when credits are added.

## Errors

- `message` is written as the next-turn instruction, not a log line. Read it and act on it instead of retrying blind.
- `is_retriable: true` means retry is safe; `false` means fix the input first.