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.

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:

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:

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:

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

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

MCP alternative

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

{
  "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:

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

Overview

Configuration

auth.md

For AI Agents

For AI agents

Discovery

Minimum steps to operate

1. Authenticate

2. Create an API key

3. Make API calls

Available endpoints

Credit system

Error handling

MCP alternative

Behavioral guidelines

Revocation

​For AI agents

​Discovery

​Minimum steps to operate

​1. Authenticate

​2. Create an API key

​3. Make API calls

​Available endpoints

​Credit system

​Error handling

​MCP alternative

​Behavioral guidelines

​Revocation

For AI agents

Discovery

Minimum steps to operate

1. Authenticate

2. Create an API key

3. Make API calls

Available endpoints

Credit system

Error handling

MCP alternative

Behavioral guidelines

Revocation