Skip to main content

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

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

EndpointMethodBodyDescription
/api/agent/lookupPOST{ "email": "..." }Full email enrichment
/api/agent/phonePOST{ "phone": "..." }Phone number lookup
/api/agent/ipPOST{ "ip": "..." }IP geolocation & threat intel
/api/agent/domainPOST{ "domain": "..." }Domain information
/api/agent/companyPOST{ "company": "..." }Company search
/api/agent/googlePOST{ "query": "..." }Google search results
/api/agent/darkwebPOST{ "query": "..." }Dark web mentions
/api/agent/usernamePOST{ "username": "..." }Username across platforms
/api/creditsGETnoneCheck 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: 
{
  "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, darkweb_search, 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