Overview

Arettic gives an agent one key and one balance for its data jobs. For verified jobs it recommends the tool that works, runs it, checks the result against a published rule and charges only if it passes. For everything else there are hundreds of provider endpoints, paid per call and free when the provider fails.

Task types

Every request names one of the task types. The list is public: GET /v1/task-types.

Test mode

Test keys start with sk_test_. They call mock providers that give the same answer every time and never spend credits, so you can build both the pass and the fail path.

curl https://api.arettic.com/v1/execute \
  -H "Authorization: Bearer $ARETTIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "mock-find-verified-email",
    "input": { "first_name": "Emily", "last_name": "Carter", "domain": "example.com" }
  }'

These inputs make the mock providers fail on purpose:

Responses

A pass returns the result. A fail returns only the reason: the data is withheld, because you didn't pay for it. Test mode also tells you what a live call would have cost, in credits and USD (1 credit = $0.001).

{
  "test_mode": true,
  "status": "passed",
  "tool_id": "mock-find-verified-email",
  "check_version": "v1",
  "result": { "email": "[email protected]", "verification_status": "valid" },
  "charged": { "credits": "0", "usd": "0.000" },
  "would_have_charged": { "credits": "38", "usd": "0.038" }
}

Data handling

Each purchase's input and result are stored encrypted with your org's own key for 7 days, so scores stay current and disputes can be checked, then deleted. An item under dispute is kept until it's decided (at most 48 hours more). Ask us to delete your data and it goes at once. After that we keep only hashes and non-personal signals (outcome, timing, coarse segment). Nothing is shared between customers, cached for others or used to train models.

Disputes

Think a charged result is wrong? Send POST /v1/disputes with the receipt_id and item_index, a reason (wrong_result, invalid_result, stale_result, duplicate_charge or other) and any evidence, within 7 days. We decide within 48 hours against the stored result; if we don't, it's upheld. Upheld disputes are refunded to your balance and count against the tool's score.

Webhooks

Owners add endpoints with POST /v1/orgs/{orgId}/webhooks; the signing secret is shown once. Events: balance.low, budget.80pct, approval.requested, approval.decided, job.completed, tool.paused, dispute.decided, price.changed and trial.expiring. Any 2xx counts as delivered; failures retry with backoff for 24 hours. Owners also get email for balance, budget, pauses, price changes, trial expiry and dispute decisions.

Verify each request: Arettic-Signature is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of <t>.<raw body> with your secret. Reject timestamps more than 5 minutes old.

Recommend

Ask which tool works for a task. Send a task_type or a plain-language task; the response says which type it chose. Tools are ranked by score, then price when scores are within 2 points. Whether a tool is sold through Arettic never changes its rank.

curl https://api.arettic.com/v1/recommend \
  -H "Authorization: Bearer $ARETTIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "task_type": "find_verified_email", "region": "US", "constraints": { "max_price": 50 }, "sort": "score" }'

Each option has its score, every score input (A, S, P, R, L, D), price_per_success, pass_rule and purchasable. Sort by score, price, value or latency.

Public data (no key)

Open under CC BY 4.0: GET /v1/task-types, /v1/tools, /v1/tools/{id}, /v1/scores, /v1/pricing, /v1/formula. Add ?mode=test to see the mock tools. Every page on this site is also available as Markdown or JSON: add .md or .json to the URL, or send an Accept header. See /llms.txt and /openapi.json.

MCP

The MCP server speaks Streamable HTTP at https://api.arettic.com/mcp. Authenticate with your agent key. Tools: list_task_types, recommend, get_tool, execute, get_job, get_receipt, open_dispute, get_approval, get_balance, search_endpoints and call_endpoint. Server card: /.well-known/mcp.json. Setup for each client: MCP server.

Org API: everything the dashboard does

Anything a person can do in the dashboard, an agent can do through the API. An org owner makes an org key on the Team page (ok_…, shown once) and the agent sends it as Authorization: Bearer ok_…. The key acts as the owner who made it, only on /v1/orgs/{orgId}/…, and a read key can only read. Keys can't make or revoke keys, and a key stops working when its maker leaves the org.

Rate limits

Public data: 120 requests a minute per IP. Sign-in emails: 20 an hour per IP. Agent keys: 600 a minute. Org endpoints: 300 a minute per org key or session. Every response carries RateLimit-* headers; over the limit you get 429 rate_limited with Retry-After.

Get an API key

A person signs in at arettic.com/app with an email link or Google. That creates the account with $1 of free credit, and the Connect page shows the key and how to plug it into Claude, Cursor, the API or the SDKs. Agents use the key; they don't create accounts.

Errors

Every error has the same shape. doc_url links to its entry on the error codes page, and retryable tells your agent whether to try again.

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or revoked API key",
    "doc_url": "https://arettic.com/docs/errors#unauthenticated",
    "retryable": false
  }
}