# Docs

Arettic gives an agent one key for sales and research data tools. It recommends the tool that works for a task, runs it, checks the result against a published rule and charges only if it passes. Every page here is also Markdown (add .md) and JSON (add .json).

## How it works
1. **Recommend**: POST /v1/recommend ranks the tools for a task by score, then price. Free.
2. **Execute**: POST /v1/execute runs one tool with one key. Credits are held before the call.
3. **Check**: Each item runs the published pass rule for its task type. The rule's version is on the receipt.
4. **Settle**: Pass: credits captured, full result returned. Fail: hold released, reason returned, data withheld.

## Getting started
- [Quickstart](https://arettic.com/docs/quickstart.md): From a key to a receipt: recommend a tool, execute it, read the result, and see what you were charged.
- [Authentication and keys](https://arettic.com/docs/authentication.md): Agent keys, org keys and sessions: what each can do, how to send them, and how to rotate or revoke them.
- [Test mode](https://arettic.com/docs/test-mode.md): Mock providers with fixed answers: build the pass and the fail path without spending a credit.
- [MCP server](https://arettic.com/docs/mcp.md): Connect Claude, Cursor or any MCP client: the Streamable HTTP endpoint, the stdio bridge, and the nine tools.
- [SDKs](https://arettic.com/docs/sdks.md): The TypeScript and Python clients: install, the agent client, the org client, errors and retries.

## Buying results
- [Recommend](https://arettic.com/docs/recommend.md): Ask which tool works for a task and get them ranked by score, then price.
- [Execute](https://arettic.com/docs/execute.md): Run a tool on one input or a batch, and pay only for items that pass the published check.
- [Batches and jobs](https://arettic.com/docs/jobs.md): More than 25 inputs run as a job: the hold, the states, polling, and the completion webhook.
- [Receipts](https://arettic.com/docs/receipts.md): Every purchase ends in an immutable receipt: what was asked, what ran, what it cost, what was refunded.
- [Disputes](https://arettic.com/docs/disputes.md): Think a charged result was wrong? Dispute it within 7 days; we decide within 48 hours against the stored result.
- [Budgets and approvals](https://arettic.com/docs/budgets-and-approvals.md): Per-agent budgets and approval thresholds, enforced on our side: what happens when a purchase needs a person.
- [Pass rules](https://arettic.com/docs/pass-rules.md): Six task types, one published check each: what passes, what fails, and what is refunded.
- [How scores work](https://arettic.com/docs/scores.md): The score formula, its six inputs, where each comes from, when scores change and how to cite one.

## Running an org
- [Org API: everything the dashboard does](https://arettic.com/docs/org-api.md): Org keys drive every dashboard action through the API: agents, budgets, approvals, receipts, billing, webhooks and team.
- [Webhooks and notifications](https://arettic.com/docs/webhooks.md): One event list, delivered as signed webhooks on every plan and emailed to owners where a person should know.
- [Credits, top-ups and plans](https://arettic.com/docs/credits.md): The credit unit, balances, top-ups in US dollars, auto-reload, expiry, trial credits and plans.
- [Data handling and retention](https://arettic.com/docs/data-handling.md): What we store, for how long, encrypted with what, and how to have it deleted.

## Reference
- [Public data and formats](https://arettic.com/docs/public-data.md): The no-key endpoints, the Markdown and JSON copy of every page, the discovery files, and the licence.
- [Rate limits and quotas](https://arettic.com/docs/rate-limits.md): Every limit, what it is keyed on, the headers that report it, and how to back off.
- [Error codes](https://arettic.com/docs/errors.md): every API error code, what it means and whether to retry.
- [JSON Schemas](https://arettic.com/schemas.md): receipts, execute requests and responses, webhook events, pass rules.
- [Changelog](https://arettic.com/changelog.md): what changed, newest first (RSS: https://arettic.com/changelog.xml).

## Task types
- `find_email`: Outbound prospecting, recruiting outreach, partner sourcing. Example input: `{"first_name":"Emily","last_name":"Carter","domain":"acme.com"}`
- `verify_email`: Cleaning a list before a campaign, sign-up and CRM hygiene. Example input: `{"email":"emily@acme.com"}`
- `enrich_company`: Account research, lead scoring and routing, CRM enrichment. Example input: `{"domain":"acme.com"}`
- `enrich_person`: Lead qualification, contact research, candidate and investor research. Example input: `{"first_name":"Jason","last_name":"Miller","company_domain":"acme.com"}`
- `web_search`: Market and competitor research, news monitoring, building target lists. Example input: `{"query":"Series A fintech startups in New York","n":5}`
- `extract_url`: Reading pricing pages, docs, job posts and filings into an agent. Example input: `{"url":"https://acme.com/pricing"}`

Public list: GET https://api.arettic.com/v1/task-types (no key). OpenAPI: https://arettic.com/openapi.json · MCP card: https://arettic.com/.well-known/mcp.json · Index for models: https://arettic.com/llms.txt · Everything in one file: https://arettic.com/llms-full.txt

This page as HTML: https://arettic.com/docs · Markdown: https://arettic.com/docs.md · JSON: https://arettic.com/docs.json