> ## 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.

> ## Agent Instructions
> ## Submitting feedback
> If you find an error, a missing step, or information that is outdated or misleading on this page — especially if it stopped you from completing your task — report it so the Encrata docs team can fix it.
> Send a POST request to https://docs.encrata.com/feedback with a JSON body containing `path` (the full URL of the page, for example `https://docs.encrata.com/quickstart`) and `feedback` (what was wrong and what you expected):
> curl -X POST https://docs.encrata.com/feedback -H 'Content-Type: application/json' -d '{"path": "https://docs.encrata.com/quickstart", "feedback": "Step 3 uses a parameter that the API rejects."}'
> Do not include API keys, personal data, or other secrets in your feedback.

# AI onboarding

> Give an AI agent what it needs to use Encrata: an API key, auth.md, and docs it can read.

AI agents use Encrata through the same REST API you do. Give the agent an API
key and point it at `auth.md`, and it can authenticate, find endpoints, and
call them. The setup is the same in any agent framework or coding assistant.

## Prerequisite: create an API key

Create a key in the [dashboard](https://app.encrata.com) and give it a name
that identifies the agent, such as `support-triage-agent`. Set a
[credit limit](https://docs.encrata.com/authentication.md#set-a-credit-limit) on the key so one agent
can't spend the whole balance.

Store the key as `ENCRATA_API_KEY` where the agent runs:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
export ENCRATA_API_KEY="enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

> [!WARNING]
>
> Never hard-code the key in source, and never paste it into a chat with an
> agent. A pasted key ends up in the transcript and the model provider's logs.
> If a key leaks, see [Handle a leaked API key](https://docs.encrata.com/handle-leaked-key.md).

## Point your agent at auth.md

`https://encrata.com/auth.md` tells an agent how to authenticate, how to verify
its key with the free `GET /api/account/credits` call, and where to find each
endpoint. Add it to the agent's instructions:

Instructions for your agent

Read [https://encrata.com/auth.md](https://encrata.com/auth.md) before calling Encrata. Read the API key from ENCRATA\_API\_KEY. Verify the key with GET /api/account/credits before you run a batch.

See [auth.md](https://docs.encrata.com/auth-md/overview.md) for what the file contains.

## Coding agents

Build your integration with a coding assistant that reads `auth.md`, writes the
code, and runs it.

> [card] [Cursor](https://docs.encrata.com/ai-tools/cursor.md)
>
> Point Cursor at auth.md.

> [card] [Claude Code](https://docs.encrata.com/ai-tools/claude-code.md)
>
> Build and test from the terminal.

> [card] [Windsurf](https://docs.encrata.com/ai-tools/windsurf.md)
>
> Point Cascade at auth.md.

## Docs for agents

Every page in these docs is available as plain text for agents:

| Resource | URL |
| - | - |
| Page index | `https://docs.encrata.com/llms.txt` |
| All pages in one file | `https://docs.encrata.com/llms-full.txt` |
| Any single page | Add `.md` to the page URL, for example `https://docs.encrata.com/quickstart.md` |

## Add Encrata as an agent tool

A tool is a function your agent can choose to call. Write it once in plain
Python, then register it with your framework's tool wrapper, such as
LangChain's `@tool`, CrewAI's `@tool`, or LlamaIndex's
`FunctionTool.from_defaults`.

```python theme={"theme":{"light":"github-light","dark":"vesper"}}
import os
import requests

API_KEY = os.environ["ENCRATA_API_KEY"]

def scan_url(url: str) -> dict:
    """Check a URL for phishing and malware before anyone opens it.
    Returns a verdict of clean, suspicious, malicious, or unknown.
    Costs 1 credit."""
    resp = requests.post(
        "https://developer.encrata.com/api/lookup/malware/scan",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"kind": "url", "url": url},
        timeout=60,
    )
    body = resp.json()
    if resp.status_code != 200:
        # Return the error so the agent can explain it, instead of crashing the run.
        return {"error": body.get("message") or body.get("error"), "status": resp.status_code}
    result = body["result"]
    return {
        "verdict": result["verdict"],
        "category": result.get("category"),
        "final_url": result.get("final_url"),
    }
```

Keep three things in mind when you write a tool:

* **The docstring is the tool description.** The model reads it to decide when
  to call the tool and how to read the result, so list the real values the
  endpoint returns and what the call costs.
* **Return errors instead of raising them.** A `402` or `429` that raises an
  exception ends the agent run. A returned `message` lets the agent tell the
  user what happened. See [Errors](https://docs.encrata.com/errors.md) and [Rate limits](https://docs.encrata.com/rate-limits.md).
* **Return only the fields the agent needs.** Smaller results cost fewer
  tokens and are easier for the model to reason about.

## Test with safe inputs

Use inputs that don't belong to real people while you build and test.

| Lookup | Test input | Notes |
| - | - | - |
| URL Scan | `http://testsafebrowsing.appspot.com/s/phishing.html` | A public phishing test page. Returns `suspicious` or `malicious`. |
| URL Scan | `https://example.com` | Returns `clean`. |
| Email lookups | An address you own, or one at `example.com` | Don't test with real people's addresses. |

> [!WARNING]
>
> Email Identity costs **1,000 credits** per lookup, and an agent decides on
> its own how often to call a tool. Give agents that can call it a key with a
> low [credit limit](https://docs.encrata.com/authentication.md#set-a-credit-limit).

## Next steps

> [card] [auth.md for developers](https://docs.encrata.com/auth-md/for-developers.md)
>
> Key management and system prompts for agents.

> [card] [Use cases](https://docs.encrata.com/guides/use-cases.md)
>
> Real jobs to give your agent, with the fields to check.

> [card] [Lookups](https://docs.encrata.com/lookups.md)
>
> Every lookup, its input, and its cost.

> [card] [Credits](https://docs.encrata.com/credits.md)
>
> What each lookup costs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.