Recommend

Ask which tool works for a task and get them ranked by score, then price.

POST /v1/recommend tells your agent which tool to use for a task. You send one of the task types, or the task in plain language. You get back the tools for that task, ranked by score, each with the price of one passing result and the check that result must pass.

The call is free: it uses no credits. It does count against your plan's daily lookup quota. Nothing is run or bought here. To buy a result, send the tool_id you pick to execute.

It needs an agent key, sk_test_… or sk_live_…, in the Authorization header (see Authentication). Test keys see mock tools. Live keys see the real catalog. Without a key you can still read the catalog and scores, unranked, through Public data.

Arettic is pre-launch. Keys go to design partners; everyone else can join the waitlist. The @arettic/sdk (npm), arettic (PyPI) and @arettic/mcp packages used on this page are published at launch.

Call it

curl -s https://api.arettic.com/v1/recommend \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "find_email",
    "region": "US",
    "constraints": { "max_price": 50, "min_score": 40 },
    "sort": "score",
    "limit": 5
  }'

This asks for find_email tools that serve the US, cost at most 50 credits per passing result and score at least 40, five at most. With a test key the only match is the mock finder:

{
  "task_type": "find_email",
  "region": "US",
  "sort": "score",
  "test_mode": true,
  "formula_version": "v1",
  "ranking": "score, then price when scores are within 2 points; purchasability never changes rank",
  "options": [
    {
      "tool_id": "mock-find-email",
      "name": "Mock Email Finder",
      "provider": "Arettic Mock Provider",
      "score": 56.53,
      "score_week": "2026-09-28",
      "score_inputs": { "A": 0.4902, "S": 0.5958, "P": 0.4902, "R": 0.7225, "L": 1, "D": 0 },
      "sample_size": 10,
      "price_per_success": { "credits": "38", "usd": "0.038" },
      "success_rate": 0.5958,
      "p50_latency_ms": 5,
      "pass_rule": "find_email@v1",
      "purchasable": true,
      "regions": ["GLOBAL", "US"]
    }
  ]
}

options[0].tool_id is what you send to execute. Check purchasable first: ranking ignores it, so the top option can be a tool that is listed for information only (see Info-only tools).

Request

POST https://api.arettic.com/v1/recommend with a JSON body. Headers: Authorization: Bearer <agent key> and Content-Type: application/json. Every field is optional, except that you must send task_type or task.

Numbers are checked strictly. constraints.max_price, constraints.min_score and limit must be non-negative numbers, or the call answers invalid_input with a message that names the field, for example "limit must be a non-negative number". A body that isn't a JSON object answers invalid_input too. An unknown sort is not an error: it falls back to score.

The task types: find_email, verify_email, enrich_company, enrich_person, web_search, extract_url. Send task_type when you know it. It skips the mapping step and the free-text quota.

Response

Each option

The formula, its weights and its rules are on How scores work and at GET https://api.arettic.com/v1/formula.

How tools are ranked

The default order is by score, highest first. Two scores within 2 points of each other count as a tie: the cheaper tool comes first, and at the same price the higher score. Tools with no score yet come after every scored tool, cheapest first.

Whether a tool can be bought through Arettic never changes its rank. It is a field, purchasable, not a factor. In the API's own tests, a tool one point below the top scorer but cheaper ranks first, and a tool 30 points below ranks last even though it is sold here.

Constraints are applied before sorting and limit after it. So sort: "price" with limit: 1 gives you the cheapest tool that meets your constraints.

Info-only tools

A tool is purchasable when it is curated for sale here and has a price. Every other listed tool is there for information only: you see its score and where it ranks, but execute refuses it with not_purchasable (HTTP 409). Its price_per_success may be null.

So take the first option with purchasable: true, not options[0]. An info-only tool is still worth reading: it shows how the tool you buy compares with the rest of the market.

Regions

region says where the results are needed. It is upper-cased, so us and US are the same. Leave it out for GLOBAL.

A tool is listed when its regions include your region or GLOBAL. Its score is the region's own score when one exists, otherwise its GLOBAL score; score_week and score_inputs come from whichever was used. The response repeats the region in region.

A region with no tools of its own, or a value that isn't a region at all, gives you the tools that serve GLOBAL with their GLOBAL scores.

Free-text tasks

When you send task instead of task_type, Arettic maps the text to a task type with a keyword classifier. It is deterministic and calls no model: the same text always gives the same type. It costs one free-text lookup from your daily quota, nothing else.

How it works: the text is lower-cased, extra spaces are collapsed, and anything after 500 characters is dropped. Each task type has a few keyword patterns with weights, for example "find … email" for find_email, "bounce" for verify_email, "search the web" for web_search. The type with the highest total wins, as long as that total is at least 2. Otherwise the call answers unknown_task_type (HTTP 400): "Couldn't map that task to a task type. Send task_type as one of: …".

The response always says what it chose, in mapped_from_task:

If the type is wrong, or confidence is low, send task_type explicitly. For example, this text matches two types and the runner-up may be the one you meant:

curl -s https://api.arettic.com/v1/recommend \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "task": "find the email and job title of the CTO at acme.com" }'

{
  "task_type": "enrich_person",
  "mapped_from_task": {
    "from": "find the email and job title of the CTO at acme.com",
    "confidence": 0.57,
    "alternatives": ["find_email"]
  },
  "region": "GLOBAL",
  "sort": "score",
  "test_mode": true,
  "formula_version": "v1",
  "ranking": "score, then price when scores are within 2 points; purchasability never changes rank",
  "options": [
    {
      "tool_id": "mock-enrich-person",
      "name": "Mock Person Enrichment",
      "provider": "Arettic Mock Provider",
      "score": 62.87,
      "score_week": "2026-09-28",
      "score_inputs": { "A": 0.5958, "S": 0.5958, "P": 0.5958, "R": 0.7225, "L": 1, "D": 0 },
      "sample_size": 10,
      "price_per_success": { "credits": "45", "usd": "0.045" },
      "success_rate": 0.5958,
      "p50_latency_ms": 5,
      "pass_rule": "enrich_person@v1",
      "purchasable": true,
      "regions": ["GLOBAL", "US"]
    }
  ]
}

Phrases from the API's own tests and where they map:

Daily quotas

Recommend is free, but each org has a daily number of lookups that depends on its plan. All the org's agents share it, and it resets at 00:00 UTC. Every call that reaches the catalog counts one score lookup, whether or not any tool matches. A call with task also counts one free-text lookup. That one is taken before the text is mapped, so a task that can't be mapped still counts, though it takes no score lookup.

When a quota is used up, the call answers HTTP 429 with the code plan_limit. The message says which limit it was. retryable is false, and the SDKs never retry recommend, so wait for the reset, or send task_type instead of task if it was the free-text quota that ran out.

{
  "error": {
    "code": "plan_limit",
    "message": "Daily limit of 1000 score lookups reached for your plan. It resets at 00:00 UTC.",
    "doc_url": "https://arettic.com/docs/errors#plan_limit",
    "retryable": false
  }
}

The per-agent rate limit applies on top of the quota: 600 requests a minute for each agent key, reported in the RateLimit-* headers. See Rate limits and quotas.

Test keys and mock tools

With a test key (sk_test_…) the catalog is the mock provider: one tool per task type, ids starting with mock-, serving GLOBAL and US. They are benchmarked and scored like real tools, so constraints and sorts behave the same way. The response has test_mode: true. A live key never sees a mock tool, and a test key never sees a real one.

So {"task_type": "find_email", "constraints": {"max_price": 10}} returns no options with a test key: the mock finder costs 38 credits. With a live key you see only the tools that are switched on in the real catalog, so a task type can have no options until its providers are live. What the mock tools return from execute is on Test mode.

SDK and MCP examples

Both SDKs read ARETTIC_API_KEY (and ARETTIC_API_URL) from the environment. Neither retries recommend, because it is a POST without an idempotency key. A refused call throws (TypeScript) or raises (Python) AretticApiError with the API's code. See SDKs.

TypeScript

import { Arettic } from "@arettic/sdk";

// Reads ARETTIC_API_KEY (and ARETTIC_API_URL) from the environment when you leave them out.
const arettic = new Arettic({ apiKey: process.env.ARETTIC_API_KEY });

const rec = await arettic.recommend({
  task_type: "find_email",
  region: "US",
  constraints: { max_price: 50, min_score: 40 },
  sort: "score",
  limit: 5,
});

// Ranking ignores whether a tool can be bought here, so take the first purchasable option.
const tool = rec.options.find((o) => o.purchasable);
if (!tool) throw new Error("No purchasable tool for " + rec.task_type + " in " + rec.region);

console.log(tool.tool_id, tool.score, tool.price_per_success?.credits, tool.pass_rule);
// mock-find-email 56.53 38 find_email@v1

// Or map plain language. The answer says which task type it chose.
const mapped = await arettic.recommend({ task: "find the work email of Emily Carter at example.com" });
console.log(mapped.task_type, mapped.mapped_from_task?.confidence); // find_email 1

Python

from arettic import Arettic

client = Arettic()  # reads ARETTIC_API_KEY (and ARETTIC_API_URL, if set)

rec = client.recommend(
    task_type="find_email",
    region="US",
    constraints={"max_price": 50, "min_score": 40},
    sort="score",
    limit=5,
)

# Ranking ignores whether a tool can be bought here, so take the first purchasable option.
tool = next((o for o in rec["options"] if o["purchasable"]), None)
if tool is None:
    raise SystemExit(f"No purchasable tool for {rec['task_type']} in {rec['region']}")

print(tool["tool_id"], tool["score"], tool["price_per_success"]["credits"], tool["pass_rule"])
# mock-find-email 56.53 38 find_email@v1

# Or map plain language. The answer says which task type it chose.
mapped = client.recommend(task="find the work email of Emily Carter at example.com")
print(mapped["task_type"], mapped["mapped_from_task"]["confidence"])  # find_email 1

MCP

The MCP server's recommend tool takes the same fields with two differences: max_price and min_score are top-level arguments (there is no constraints object), and there is no limit, so you get up to 10 options. task is limited to 500 characters, region to 10, and min_score to 100. The result is the same JSON as above, as one text content block. A refused call comes back as a result with isError: true and the API's error body. Setup is on MCP server.

{
  "name": "recommend",
  "arguments": {
    "task_type": "find_email",
    "region": "US",
    "max_price": 50,
    "min_score": 40,
    "sort": "score"
  }
}

Errors

Every error is { "error": { "code", "message", "doc_url", "retryable" } }. doc_url points at the code's entry on Error codes.

Updated 2026-09-29 · This page as Markdown · JSON