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

# For AI Agents

> How AI agents discover, authenticate, and operate with Encrata using auth.md.

# For AI agents

This guide is for AI agents (LLM-based systems that need to autonomously authenticate with and use Encrata's APIs). If you're a developer configuring an agent, see [For Developers](/auth-md/for-developers).

## Discovery

Fetch the auth file from Encrata's domain:

```
GET https://encrata.com/auth.md
```

The file contains everything needed to authenticate and operate. Parse it once at startup and cache locally. It changes only on API updates.

## Minimum steps to operate

### 1. Authenticate

If you have an API key (format: `enc_live_` + 32 chars), skip to step 3.

If you have user credentials:

```http theme={"dark"}
POST https://encrata.com/api/auth/login
Content-Type: application/json

{
  "email": "<user_email>",
  "password": "<user_password>"
}
```

### 2. Create an API key

Use the session token from step 1:

```http theme={"dark"}
POST https://encrata.com/api/keys
Authorization: Bearer <session_token>
Content-Type: application/json

{
  "name": "<descriptive_name>"
}
```

Store the returned `key` value securely. It's shown exactly once.

### 3. Make API calls

Use the API key as a Bearer token:

```http theme={"dark"}
POST https://encrata.com/api/agent/lookup
Authorization: Bearer enc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "email": "target@example.com"
}
```

## Available endpoints

| Endpoint                  | Method | Body                    | Description                   |
| ------------------------- | ------ | ----------------------- | ----------------------------- |
| `/api/agent/lookup`       | POST   | `{ "email": "..." }`    | Full email enrichment         |
| `/api/agent/phone`        | POST   | `{ "phone": "..." }`    | Phone number lookup           |
| `/api/agent/ip`           | POST   | `{ "ip": "..." }`       | IP geolocation & threat intel |
| `/api/agent/domain`       | POST   | `{ "domain": "..." }`   | Domain information            |
| `/api/agent/company`      | POST   | `{ "company": "..." }`  | Company search                |
| `/api/agent/google`       | POST   | `{ "query": "..." }`    | Google search results         |
| `/api/agent/darkweb`      | POST   | `{ "query": "..." }`    | Dark web mentions             |
| `/api/agent/onion-search` | POST   | `{ "query": "..." }`    | Find onion sites by keyword   |
| `/api/agent/onion-render` | POST   | `{ "url": "..." }`      | Fetch an onion page over Tor  |
| `/api/agent/username`     | POST   | `{ "username": "..." }` | Username across platforms     |
| `/api/credits`            | GET    | none                    | Check remaining credits       |

## Credit system

Every lookup costs credits:

* **Check balance** before expensive operations: `GET /api/credits`
* **Handle 402** responses gracefully. Alert the user that credits are exhausted
* **Don't retry** on 402. The operation won't succeed without a top-up

## Error handling

```
401 → Key invalid or revoked. Re-authenticate.
402 → No credits. Alert user.
429 → Rate limited. Wait for Retry-After header value, then retry.
422 → Bad request. Fix the request body.
500 → Server error. Retry with exponential backoff (max 3 attempts).
```

## MCP alternative

If your platform supports MCP, you can skip HTTP entirely:

```json theme={"dark"}
{
  "mcpServers": {
    "encrata": {
      "url": "https://encrata.com/mcp",
      "headers": {
        "Authorization": "Bearer enc_live_xxx..."
      }
    }
  }
}
```

Tools available: `lookup_email`, `lookup_phone`, `lookup_ip`, `lookup_domain`, `lookup_company`, `google_search`, `google_dork`, `darkweb_search`, `onion_search`, `onion_render`, `username_search`, `check_credits`.

## Behavioral guidelines

* **Be efficient** - batch related lookups when possible rather than making many sequential calls
* **Respect rate limits** - self-throttle to avoid 429 responses
* **Cache results** - enrichment data doesn't change frequently, cache for at least 1 hour
* **Check credits proactively** - before starting a batch of lookups, verify sufficient balance
* **Handle failures gracefully** - never crash on API errors, always have a fallback response for the user

## Revocation

API keys can be revoked at any time by the user via their dashboard or the API. If you receive a 401 on a previously-working key:

1. Do not attempt to create a new key automatically
2. Inform the user that access has been revoked
3. Wait for the user to provide a new key or re-authorize