Overview

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.

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-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-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_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 and get_balance. Server card: /.well-known/mcp.json.

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. Waitlist: 10 an hour 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.

Join the waitlist from an agent

curl https://api.arettic.com/v1/waitlist \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "use_case": "lead research agent" }'

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
  }
}