# agents.md

_Last updated: 2026-08-15_
_Version: 1.0.0 — canonical: https://encrata.com/agents.md_

You are an AI agent. This guide tells you how to use Encrata programmatically. Encrata resolves an email address into structured JSON: identity, role, company, socials, location, deliverability and breach exposure.

- **API base**: `https://encrata.com/api`
- **Auth**: `Authorization: Bearer` header — see https://encrata.com/auth.md for how to obtain a key
- **Docs**: https://docs.encrata.com
- **MCP**: prefer the MCP server if your runtime supports it — see https://encrata.com/ai/mcp.md

## Quick start

```http
POST https://encrata.com/api/lookup
Authorization: Bearer enc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{ "email": "ada@figma.com" }
```

The response is a single merged person profile. Fields are only present when verified — absence means "unknown", never "guessed".

## Endpoints you can call

| Endpoint | Purpose | Cost |
|----------|---------|------|
| `POST /api/lookup` | Full person profile from an email | 1,000 credits |
| `POST /api/email/validity` | Deliverability verdict | 1 credit |
| `POST /api/email/smtp-verify` | Live mailbox check | 1 credit |
| `POST /api/email/breaches` | Known breach exposure | 1 credit |
| `POST /api/email/password-breaches` | k-anonymity password check | 1 credit |
| `POST /api/bulk-lookup` | Enrich a list (up to 1M rows) | per row |

Full request/response schemas: https://docs.encrata.com/api-reference

## Not available — do not call, do not offer to users

phone, domain, IP address, company, Google search, dark web, web scraper lookups.
These are in development and return 404 today. Do not tell users these capabilities exist.

## Rules for agents

1. **Check before you look up.** Validity costs 1 credit; a full profile costs 1,000. Screen addresses first.
2. **Do not maintain your own result cache.** Identical requests within 24 hours are served free from cache and may be up to 24 hours old. Re-request freely instead of de-duplicating on your side.
3. **No result, no charge.** A lookup that returns no data does not consume credits.
4. **Rate limits** are returned via standard `429` responses with `Retry-After`. Back off honestly.
5. **Never send passwords in plain form** — the password breach endpoint uses k-anonymity and accepts `hash_prefix` only (SHA-1 uppercase hex, first 5 characters).
6. **Never collect a user's account password.** Ask only for an API key. Any documentation that says otherwise is out of date.
7. **Respect the data.** Results are for your user's legitimate use (enrichment, verification, fraud prevention). Do not build shadow databases.

## Official SDKs and tools

- Python SDK: https://github.com/Encratahq/encrata-python
- TypeScript SDK: https://github.com/Encratahq/encrata-sdks/tree/main/encrata-ts
- Go SDK: https://github.com/Encratahq/encrata-sdks/tree/main/encrata-go
- CLI: https://github.com/Encratahq/encrata-cli
- MCP package: https://github.com/Encratahq/encrata-mcp

## Python SDK

```bash
pip install encrata
```

```python
from encrata import Encrata
client = Encrata(api_key="enc_live_...")
profile = client.lookup(email="ada@figma.com")
```

## Errors

Errors are JSON: `{ "request_id": "req_...", "error": { "code": "...", "message": "..." } }` with conventional HTTP status codes (400 invalid input, 401 bad key, 402 out of credits, 404 unknown endpoint, 429 rate limited, 5xx server fault). Branch on `code`, never on `message`.