{ "page": "docs/quickstart", "title": "Quickstart", "slug": "quickstart", "description": "From a key to a receipt: recommend a tool, execute it, read the result, and see what you were charged.", "section": "Getting started", "updated": "2026-09-29", "blocks": [ { "type": "p", "text": "This page takes you from nothing to a receipt. You get a key, ask which tool works for a task, buy one result, read the answer, and then do the same with a live key. Every step shows curl, the TypeScript SDK and the Python SDK, and the MCP tool where there is one. Start with a test key: it buys from mock tools, so nothing is charged while you build." }, { "type": "note", "text": "Arettic is pre-launch. Keys go to design partners first. Everyone else joins the waitlist at [/waitlist](/waitlist) and gets an invite when self-serve sign-up opens: a key with $1 of credits, test mode with mock providers, and the MCP server. The `@arettic/sdk` and `@arettic/mcp` packages (npm) and the `arettic` package (PyPI) are published at launch. The curl examples work as written for anyone who has a key." }, { "type": "h2", "id": "get-a-key", "text": "1. Get a key" }, { "type": "list", "ordered": true, "items": [ "Sign in at [/app](/app) with your work email. You get a one-time link by email. It works once and expires in 15 minutes. The same link creates your account if you're new.", "Create an org. Give it a name of 2 to 100 characters. Creating the org gives it $1 of trial credits (1,000 credits) that last 30 days.", "Open Agents and add an agent. Pick a name, the mode **Test** (mock tools, no credits move), a monthly budget (default $50) and when to ask you before a purchase (default: any single purchase over $20). You can't change the mode later, so make a second agent for live when you get there.", "Copy the key. It starts with `sk_test_` and is shown once, on the same page, in a box that disappears after 2 minutes. Arettic keeps only a SHA-256 hash of it, so it can't show it again. Lost it? Rotate the key on the same page; the old one stops at once." ] }, { "type": "p", "text": "Put the key in the `ARETTIC_API_KEY` environment variable. Both SDKs and the MCP bridge read it. Every request to the API sends it as `Authorization: Bearer sk_test_…`." }, { "type": "code", "title": "Shell", "lang": "bash", "code": "export ARETTIC_API_KEY=sk_test_…\n# ARETTIC_API_URL is optional. The default is https://api.arettic.com." }, { "type": "code", "title": "Install the SDKs (published at launch)", "lang": "bash", "code": "npm install @arettic/sdk # TypeScript. No dependencies; needs Node 18+ or any runtime with fetch.\npip install arettic # Python 3.9+. Standard library only." }, { "type": "p", "text": "Doing this from code instead of the dashboard? A signed-in session or an org key can create agents with `POST /v1/orgs/{orgId}/agents`; the answer carries the key once. See [Authentication and keys](/docs/authentication) and the [org API](/docs/org-api)." }, { "type": "h2", "id": "recommend", "text": "2. Ask which tool works" }, { "type": "p", "text": "Send a task type. Arettic ranks every tool that can do it by score, then by price when scores are within 2 points. Whether a tool can be bought through Arettic never changes its rank, so pick the first option with `purchasable: true`. The call is free; it counts against your plan's daily score lookups (1,000 a day on pay as you go)." }, { "type": "p", "text": "With a test key the options are mock tools, and their ids start with `mock-`. With a live key they're real tools." }, { "type": "code", "title": "curl", "lang": "bash", "code": "curl https://api.arettic.com/v1/recommend \\\n -H \"Authorization: Bearer $ARETTIC_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"task_type\": \"verify_email\", \"region\": \"US\" }'" }, { "type": "code", "title": "TypeScript", "lang": "ts", "code": "import { Arettic } from \"@arettic/sdk\";\n\n// Reads ARETTIC_API_KEY (and ARETTIC_API_URL) from the environment when you leave them out.\nconst arettic = new Arettic({ apiKey: process.env.ARETTIC_API_KEY });\n\nconst { options } = await arettic.recommend({ task_type: \"verify_email\", region: \"US\" });\nconst tool = options.find((o) => o.purchasable);\nif (!tool) throw new Error(\"No purchasable tool for verify_email\");\nconsole.log(tool.tool_id, tool.price_per_success); // \"mock-verify-email\" with a test key" }, { "type": "code", "title": "Python", "lang": "python", "code": "from arettic import Arettic\n\nclient = Arettic() # reads ARETTIC_API_KEY (and ARETTIC_API_URL, if set)\n\nrec = client.recommend(task_type=\"verify_email\", region=\"US\")\ntool_id = next(o[\"tool_id\"] for o in rec[\"options\"] if o[\"purchasable\"])\nprint(tool_id) # \"mock-verify-email\" with a test key" }, { "type": "p", "text": "From an MCP client, connect once and the model calls the `recommend` tool itself. With Claude Code, add the stdio bridge (published at launch). Any client that speaks Streamable HTTP can instead connect to `https://api.arettic.com/mcp` with the same `Authorization: Bearer` header. Claude Desktop and Cursor configs are on [MCP server](/docs/mcp)." }, { "type": "code", "title": "Claude Code", "lang": "bash", "code": "claude mcp add arettic --env ARETTIC_API_KEY=sk_test_… -- npx -y @arettic/mcp" }, { "type": "code", "title": "MCP tool call", "lang": "json", "code": "{ \"name\": \"recommend\", \"arguments\": { \"task_type\": \"verify_email\", \"region\": \"US\" } }" }, { "type": "p", "text": "The MCP `recommend` tool takes `task_type` or a plain-language `task`, plus `region`, `max_price`, `min_score` and `sort`, all as top-level arguments. Over REST, `max_price` and `min_score` go inside `constraints`." }, { "type": "code", "title": "Response (example)", "lang": "json", "code": "{\n \"task_type\": \"verify_email\",\n \"region\": \"US\",\n \"sort\": \"score\",\n \"test_mode\": true,\n \"formula_version\": \"v1\",\n \"ranking\": \"score, then price when scores are within 2 points; purchasability never changes rank\",\n \"options\": [\n {\n \"tool_id\": \"mock-verify-email\",\n \"name\": \"Mock Email Verifier\",\n \"provider\": \"Arettic Mock Provider\",\n \"score\": 62.87,\n \"score_week\": \"2026-09-28\",\n \"score_inputs\": { \"A\": 0.5958, \"S\": 0.5958, \"P\": 0.5958, \"R\": 0.7225, \"L\": 1, \"D\": 0 },\n \"sample_size\": 10,\n \"price_per_success\": { \"credits\": \"6\", \"usd\": \"0.006\" },\n \"success_rate\": 0.5958,\n \"p50_latency_ms\": 5,\n \"pass_rule\": \"verify_email@v1\",\n \"purchasable\": true,\n \"regions\": [\"GLOBAL\", \"US\"]\n }\n ]\n}" }, { "type": "p", "text": "Each option carries its `score` (0 to 100), the six score inputs, `price_per_success` in credits and USD (1 credit = $0.001), the `pass_rule` its results are checked against, and `purchasable`. Send a plain-language `task` instead of `task_type` and the answer says which type it chose in `mapped_from_task`. Every field, sort and constraint is on [Recommend](/docs/recommend)." }, { "type": "h2", "id": "execute", "text": "3. Buy one result" }, { "type": "p", "text": "Send the `tool_id` and one `input`. The input fields come from the task type: for `verify_email` it's `{ \"email\": \"…\" }`. With a test key the mock provider answers and the real pass rule runs on its answer. No credits move." }, { "type": "code", "title": "curl", "lang": "bash", "code": "curl https://api.arettic.com/v1/execute \\\n -H \"Authorization: Bearer $ARETTIC_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"tool_id\": \"mock-verify-email\", \"input\": { \"email\": \"jason@acme.com\" } }'" }, { "type": "code", "title": "TypeScript", "lang": "ts", "code": "const bought = await arettic.execute({\n tool_id: tool.tool_id,\n input: { email: \"jason@acme.com\" },\n});\n\nif (bought.status === \"passed\" || bought.status === \"partial\") {\n console.log(bought.result, bought.charged); // charged is 0 in test mode\n} else if (bought.status === \"failed\") {\n console.log(\"Not charged:\", bought.reason);\n}" }, { "type": "code", "title": "Python", "lang": "python", "code": "res = client.execute({\"tool_id\": tool_id, \"input\": {\"email\": \"jason@acme.com\"}})\nprint(res[\"status\"], res.get(\"result\"), res.get(\"reason\"))\nprint(res[\"would_have_charged\"]) # test mode: what a live key would have paid" }, { "type": "code", "title": "MCP tool call", "lang": "json", "code": "{ \"name\": \"execute\", \"arguments\": { \"tool_id\": \"mock-verify-email\", \"input\": { \"email\": \"jason@acme.com\" } } }" }, { "type": "code", "title": "Response (example)", "lang": "json", "code": "{\n \"test_mode\": true,\n \"tool_id\": \"mock-verify-email\",\n \"task_type\": \"verify_email\",\n \"check_version\": \"v1\",\n \"charged\": { \"credits\": \"0\", \"usd\": \"0.000\" },\n \"status\": \"passed\",\n \"result\": { \"email\": \"jason@acme.com\", \"status\": \"valid\" },\n \"would_have_charged\": { \"credits\": \"6\", \"usd\": \"0.006\" }\n}" }, { "type": "p", "text": "The SDKs add an `idempotency_key` to every execute call, so a retry after a dropped connection can never buy twice. From curl, send your own (up to 200 characters) once you go live. `execute` also takes `inputs` (a list of up to 1,000), `max_price` (the most you'll pay for the whole request, in credits), `approval_id` and `fallback`. All of it is on [Execute](/docs/execute)." }, { "type": "h2", "id": "read-the-response", "text": "4. Read the response" }, { "type": "p", "text": "Look at `status` first." }, { "type": "table", "caption": "Execute statuses", "head": [ "Status", "What happened", "What you get" ], "rows": [ [ "passed", "The result passed the published check for its task type.", "`result`, and `charged` (the price). In test mode `charged` is 0 and `would_have_charged` shows the price." ], [ "failed", "The result didn't pass the check, or the provider errored.", "`reason` only. The data is withheld and nothing is charged. In test mode `would_have_charged` is 0." ], [ "partial", "Web search only: fewer results than asked for.", "`result` and `reason` (for example `results:2/5`). Charged pro rata." ], [ "completed", "A batch of 2 to 25 `inputs` finished.", "`summary` (items, passed, partial, failed) and `items[]`, one entry per input with its own status." ], [ "queued", "Over 25 inputs with a live key: the request runs as a job (HTTP 202). Test keys run every batch inline.", "`job_id`. Poll `GET /v1/jobs/{job_id}`, or use `waitForJob` / `wait_for_job` in the SDKs. See [Batches and jobs](/docs/jobs)." ], [ "approval_required", "A live purchase over the agent's approval threshold or its monthly budget (HTTP 202). An owner has been emailed.", "`approval_id` and `expires_at` (24 hours). Poll `GET /v1/approvals/{approval_id}`, then send the same request again with `approval_id`. See [Budgets and approvals](/docs/budgets-and-approvals)." ] ] }, { "type": "p", "text": "The fields of a single-input answer:" }, { "type": "table", "caption": "Execute response fields", "head": [ "Field", "Meaning" ], "rows": [ [ "test_mode", "`true` on answers to a test key. Absent on live answers." ], [ "tool_id, task_type", "The tool that ran and its task type." ], [ "check_version", "The version of the pass rule that judged the result (`v1`). It's on the receipt too." ], [ "charged", "What was taken, as credits and USD: `{ \"credits\": \"6\", \"usd\": \"0.006\" }`. Always 0 in test mode." ], [ "would_have_charged", "Test mode only: what a live key would have paid for this answer." ], [ "result", "The provider's answer. Present on `passed` and `partial` only." ], [ "reason", "Why it failed or was partial: for example `status:unknown`, `no_result`, `provider_error`, `timeout`, `blocked_page`." ], [ "execution_id, receipt_id, refunded", "Live only: this item's id, the receipt for the whole request, and the credits that were held but not taken." ] ] }, { "type": "p", "text": "Try the fail path now. The mock verifier fails any address that starts with `unknown`. An address that starts with `bad` comes back `invalid`, which is a definitive answer, so it passes and would be charged. Any input that contains `provider-error` gives `provider_error`, and `nomatch` gives `no_result`. The inputs for every mock tool are on [Test mode](/docs/test-mode)." }, { "type": "code", "title": "curl", "lang": "bash", "code": "curl https://api.arettic.com/v1/execute \\\n -H \"Authorization: Bearer $ARETTIC_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"tool_id\": \"mock-verify-email\", \"input\": { \"email\": \"unknown@acme.com\" } }'" }, { "type": "code", "title": "Response (example)", "lang": "json", "code": "{\n \"test_mode\": true,\n \"tool_id\": \"mock-verify-email\",\n \"task_type\": \"verify_email\",\n \"check_version\": \"v1\",\n \"charged\": { \"credits\": \"0\", \"usd\": \"0.000\" },\n \"status\": \"failed\",\n \"reason\": \"status:unknown\",\n \"would_have_charged\": { \"credits\": \"0\", \"usd\": \"0.000\" }\n}" }, { "type": "p", "text": "Anything the API refuses comes back as an error with one shape, and the SDKs raise it as `AretticApiError`. `invalid_input` (HTTP 400) is free: the input is checked before any provider is called, and `message` names the field. `unknown_tool` (404) means the id isn't in the catalog your key can see; a live key sees no `mock-` tools. `unauthenticated` (401) means the key is missing, wrong or revoked. Every code is on [Error codes](/docs/errors). `doc_url` links to the code's entry and `retryable` says whether sending the same request again can work." }, { "type": "code", "title": "Response (example)", "lang": "json", "code": "{\n \"error\": {\n \"code\": \"invalid_input\",\n \"message\": \"input.email: must be an email address. Nothing was charged.\",\n \"doc_url\": \"https://arettic.com/docs/errors#invalid_input\",\n \"retryable\": false\n }\n}" }, { "type": "h3", "id": "other-task-types", "text": "Any task, the same call" }, { "type": "p", "text": "Email is only the first example. Every task type works the same way: pick the tool from `recommend`, send its `input`, and pay only if the result passes. With a test key, these mock tools answer each task type:" }, { "type": "table", "caption": "Every task type, its test tool and an example input", "head": [ "Task type", "Used for", "Test tool", "Example input" ], "rows": [ [ "`find_email`", "Outbound prospecting, recruiting outreach, partner sourcing", "`mock-find-email`", "`{\"first_name\":\"Emily\",\"last_name\":\"Carter\",\"domain\":\"acme.com\"}`" ], [ "`verify_email`", "Cleaning a list before a campaign, sign-up and CRM hygiene", "`mock-verify-email`", "`{\"email\":\"emily@acme.com\"}`" ], [ "`enrich_company`", "Account research, lead scoring and routing, CRM enrichment", "`mock-enrich-company`", "`{\"domain\":\"acme.com\"}`" ], [ "`enrich_person`", "Lead qualification, contact research, candidate and investor research", "`mock-enrich-person`", "`{\"first_name\":\"Jason\",\"last_name\":\"Miller\",\"company_domain\":\"acme.com\"}`" ], [ "`web_search`", "Market and competitor research, news monitoring, building target lists", "`mock-web-search`", "`{\"query\":\"Series A fintech startups in New York\",\"n\":5}`" ], [ "`extract_url`", "Reading pricing pages, docs, job posts and filings into an agent", "`mock-extract-url`", "`{\"url\":\"https://acme.com/pricing\"}`" ] ] }, { "type": "h2", "id": "go-live", "text": "5. Switch to a live key" }, { "type": "p", "text": "Add a second agent on the Agents page and pick the mode **Live**. Its key starts with `sk_live_`. Change nothing else: the same code and the same endpoints. Three things are different." }, { "type": "list", "items": [ "`recommend` returns real tools with real prices. A live key can't see `mock-` tools; asking for one answers `unknown_tool`.", "`execute` holds the price in credits before the call, calls the provider with Arettic's own credentials, runs the check, and settles. A pass captures the hold. A fail releases it. The answer adds `execution_id`, `receipt_id` and `refunded`, and `charged` is real.", "Your org needs credits. The $1 of trial credits from sign-up is spent first. An org that has never topped up can spend at most 50 credits an hour. Top up on the Billing page; the first top-up is $20. See [Credits, top-ups and plans](/docs/credits)." ] }, { "type": "p", "text": "Send an `idempotency_key` with every live purchase. If the connection drops and you send the same request again with the same key, you get the first answer back with `replayed: true`, never a second charge. The SDKs make a key for each call; pass your own to keep retries safe across restarts of your program." }, { "type": "code", "title": "curl", "lang": "bash", "code": "curl https://api.arettic.com/v1/execute \\\n -H \"Authorization: Bearer $ARETTIC_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"tool_id\": \"hunter-verify-email\",\n \"input\": { \"email\": \"jason@acme.com\" },\n \"idempotency_key\": \"quickstart-1\"\n }'" }, { "type": "code", "title": "TypeScript", "lang": "ts", "code": "const live = new Arettic({ apiKey: process.env.ARETTIC_API_KEY }); // an sk_live_… key\n\nconst bought = await live.execute(\n { tool_id: \"hunter-verify-email\", input: { email: \"jason@acme.com\" } },\n { idempotencyKey: \"quickstart-1\" },\n);\n\n// Live answers carry a receipt_id: fetch the receipt with the same key.\nif (\"receipt_id\" in bought) {\n const receipt = await live.receipt(bought.receipt_id);\n console.log(receipt.charged, receipt.items[0]?.outcome); // { credits: \"7\", usd: \"0.007\" } \"captured\"\n}" }, { "type": "code", "title": "Python", "lang": "python", "code": "live = Arettic(api_key=\"sk_live_…\")\n\nres = live.execute(\n {\"tool_id\": \"hunter-verify-email\", \"input\": {\"email\": \"jason@acme.com\"}},\n idempotency_key=\"quickstart-1\",\n)\nprint(res[\"status\"], res[\"charged\"][\"credits\"])\n\n# Live answers carry a receipt_id: fetch the receipt with the same key.\nreceipt = live.receipt(res[\"receipt_id\"])\nfor item in receipt[\"items\"]:\n print(item[\"provider\"], item[\"outcome\"], item[\"charged\"][\"credits\"])" }, { "type": "code", "title": "Response (example)", "lang": "json", "code": "{\n \"status\": \"passed\",\n \"execution_id\": \"c02576cf-b3ce-4b0f-a30c-6e8aad4328ce\",\n \"receipt_id\": \"67a1fb46-c554-4cf6-b4e2-df1dbdf0e936\",\n \"tool_id\": \"hunter-verify-email\",\n \"task_type\": \"verify_email\",\n \"check_version\": \"v1\",\n \"charged\": { \"credits\": \"7\", \"usd\": \"0.007\" },\n \"refunded\": { \"credits\": \"0\", \"usd\": \"0.000\" },\n \"result\": { \"email\": \"jason@acme.com\", \"status\": \"valid\" }\n}" }, { "type": "p", "text": "Use the `tool_id` your live `recommend` returned; `hunter-verify-email` and its 7-credit price are an example. On a fail the answer has `reason`, `charged` is 0 and `refunded` is the full price: the hold went back to your balance." }, { "type": "h3", "id": "receipt", "text": "Fetch the receipt" }, { "type": "p", "text": "Every live purchase writes one immutable receipt: what was asked (as a hash), which provider answered, the check and its version, and, per item, what was charged and refunded. Fetch it by id with the same key. Any agent of the org can read the org's receipts, and they're on the dashboard under Receipts." }, { "type": "code", "title": "curl", "lang": "bash", "code": "curl https://api.arettic.com/v1/receipts/67a1fb46-c554-4cf6-b4e2-df1dbdf0e936 \\\n -H \"Authorization: Bearer $ARETTIC_API_KEY\"" }, { "type": "code", "title": "MCP tool call", "lang": "json", "code": "{ \"name\": \"get_receipt\", \"arguments\": { \"receipt_id\": \"67a1fb46-c554-4cf6-b4e2-df1dbdf0e936\" } }" }, { "type": "code", "title": "Response (example)", "lang": "json", "code": "{\n \"receipt_id\": \"67a1fb46-c554-4cf6-b4e2-df1dbdf0e936\",\n \"created_at\": \"2026-09-29T18:04:11.512Z\",\n \"tool_id\": \"hunter-verify-email\",\n \"job_id\": null,\n \"idempotency_key\": \"quickstart-1\",\n \"request_hash\": \"23350b3dcc6226289d9d6f4bdb8ccf7d7258c28317131242e6e566de6c8db75d\",\n \"check_version\": \"v1\",\n \"charged\": { \"credits\": \"7\", \"usd\": \"0.007\" },\n \"refunded\": { \"credits\": \"0\", \"usd\": \"0.000\" },\n \"summary\": { \"items\": 1, \"passed\": 1, \"partial\": 0, \"failed\": 0 },\n \"items\": [\n {\n \"index\": 0,\n \"execution_id\": \"c02576cf-b3ce-4b0f-a30c-6e8aad4328ce\",\n \"tool_id\": \"hunter-verify-email\",\n \"provider\": \"hunter\",\n \"outcome\": \"captured\",\n \"charged\": { \"credits\": \"7\", \"usd\": \"0.007\" },\n \"refunded\": { \"credits\": \"0\", \"usd\": \"0.000\" },\n \"pricing_mode\": \"per_success\",\n \"input_hash\": \"ab5c971d93369517129c982ea1dc700e48f8c9f851aa78deef918c40d9af3828\",\n \"result_hash\": \"4e2efddb74f95b6ac46553aab5d2a016e3f3877ceeffa14f4eb2bae0be6ab637\",\n \"check_version\": \"v1\",\n \"settled_at\": \"2026-09-29T18:04:11.498Z\"\n }\n ]\n}" }, { "type": "p", "text": "`outcome` is the ledger state of the item: `captured` means charged, `released` means not charged. `input_hash` and `result_hash` are SHA-256 of the canonical JSON (keys sorted, no spaces), so you can check a result you stored against its receipt. Test keys write no receipts. The receipt field by field, the list endpoint and the CSV export are on [Receipts](/docs/receipts). Think a charged result is wrong? Dispute it within 7 days: [Disputes](/docs/disputes)." }, { "type": "p", "text": "To see what's left, call `GET /v1/balance` (`balance()` in both SDKs, `get_balance` over MCP). It returns the org's credits, paid and trial, plus this agent's month-to-date spend, its budget and what remains of it." }, { "type": "code", "title": "Response (example)", "lang": "json", "code": "{\n \"org_balance\": {\n \"paid\": { \"credits\": \"0\", \"usd\": \"0.000\" },\n \"trial\": { \"credits\": \"1000\", \"usd\": \"1.000\" },\n \"total\": { \"credits\": \"1000\", \"usd\": \"1.000\" }\n },\n \"agent_spent_month\": { \"credits\": \"0\", \"usd\": \"0.000\" },\n \"agent_budget\": { \"credits\": \"50000\", \"usd\": \"50.000\" },\n \"agent_budget_left\": { \"credits\": \"50000\", \"usd\": \"50.000\" }\n}" }, { "type": "h2", "id": "where-next", "text": "Where next" }, { "type": "list", "items": [ "[Test mode](/docs/test-mode): every mock tool and the inputs that make it pass, fail or go partial.", "[Execute](/docs/execute): every request field, batches, `max_price`, fallback, idempotency, and each status with its fields.", "[Receipts](/docs/receipts): the receipt field by field, listing and filtering, and the CSV export.", "[Budgets and approvals](/docs/budgets-and-approvals): the monthly budget, the approval threshold, and what your agent does while an owner decides.", "[MCP server](/docs/mcp): the hosted endpoint, the stdio bridge, client configs and all nine tools.", "[SDKs](/docs/sdks): every method of the TypeScript and Python clients, errors and retries.", "[Error codes](/docs/errors) and the [JSON Schemas](/schemas) for requests, responses and receipts." ] } ] }