SDKs

npm install @arettic/sdk

pip install arettic

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

const arettic = new Arettic({
  apiKey: process.env.ARETTIC_API_KEY,
  baseUrl: "https://api.arettic.com",
  maxRetries: 3, // the default
  timeoutMs: 60_000, // per attempt; the default
  userAgent: "research-bot/1.0", // goes in front of arettic-sdk-ts/0.1.0
});

import os

from arettic import Arettic

client = Arettic(
    api_key=os.environ["ARETTIC_API_KEY"],
    base_url="https://api.arettic.com",
    max_retries=3,  # the default
    timeout=60.0,  # seconds; the default
)

{
  "test_mode": true,
  "tool_id": "mock-verify-email",
  "task_type": "verify_email",
  "check_version": "v1",
  "charged": { "credits": "0", "usd": "0.000" },
  "status": "passed",
  "result": { "email": "[email protected]", "status": "valid" },
  "would_have_charged": { "credits": "6", "usd": "0.006" }
}

{
  "status": "passed",
  "execution_id": "6b1d3f0e-2c4a-4f8e-9a7b-1c2d3e4f5a6b",
  "receipt_id": "0f7a9c2d-5e6b-4a1c-8d9e-2f3a4b5c6d7e",
  "tool_id": "hunter-verify-email",
  "task_type": "verify_email",
  "check_version": "v1",
  "charged": { "credits": "7", "usd": "0.007" },
  "refunded": { "credits": "0", "usd": "0.000" },
  "result": { "email": "[email protected]", "status": "valid" }
}

{
  "status": "approval_required",
  "approval_id": "a1c2e3f4-5b6a-4d7c-8e9f-0a1b2c3d4e5f",
  "reason": "over_threshold",
  "amount": { "credits": "25000", "usd": "25.000" },
  "expires_at": "2026-09-30T09:12:45.000Z",
  "message": "This is above the agent's approval threshold. An owner has been asked to approve it; retry with approval_id once approved."
}

{
  "status": "queued",
  "job_id": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
  "items": 100,
  "max_charge": { "credits": "700", "usd": "0.700" },
  "poll": "/v1/jobs/9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
  "message": "Running 100 items as a job. Poll the job for progress; each item is charged only if it passes."
}

const inputs = [
  { first_name: "Emily", last_name: "Carter", domain: "acme.com" },
  { first_name: "Jason", last_name: "Miller", domain: "example.com" },
  // ... up to 1,000
];
let bought = await arettic.execute({ tool_id: toolId, inputs });

if (bought.status === "approval_required") {
  const approval = await arettic.waitForApproval(bought.approval_id, { intervalMs: 10_000 });
  if (approval.status !== "approved") throw new Error("Approval " + approval.status);
  // The same tool and inputs, or the API answers approval_mismatch.
  bought = await arettic.execute({ tool_id: toolId, inputs, approval_id: approval.approval_id });
}

if (bought.status === "queued") {
  const job = await arettic.waitForJob(bought.job_id, { timeoutMs: 30 * 60_000 });
  console.log(job.status, job.summary, job.receipt_id);
}

import time

inputs = [
    {"first_name": "Emily", "last_name": "Carter", "domain": "acme.com"},
    {"first_name": "Jason", "last_name": "Miller", "domain": "example.com"},
    # ... up to 1,000
]
bought = client.execute(tool_id=tool_id, inputs=inputs)

if bought["status"] == "approval_required":
    approval = client.approval(bought["approval_id"])
    while approval["status"] == "pending":
        time.sleep(10)
        approval = client.approval(bought["approval_id"])
    if approval["status"] != "approved":
        raise RuntimeError("Approval " + approval["status"])
    # The same tool and inputs, or the API answers approval_mismatch.
    bought = client.execute(tool_id=tool_id, inputs=inputs, approval_id=approval["approval_id"])

if bought["status"] == "queued":
    job = client.wait_for_job(bought["job_id"], interval=5.0, timeout=1800.0)
    print(job["status"], job.get("summary"), job.get("receipt_id"))

{
  "job_id": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
  "status": "running",
  "items": 100,
  "progress": 37,
  "created_at": "2026-09-29T09:12:45.000Z",
  "started_at": "2026-09-29T09:12:47.000Z",
  "finished_at": null
}

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

const org = new AretticOrg({
  apiKey: process.env.ARETTIC_ORG_KEY, // with none, ARETTIC_API_KEY
  orgId: "your-org-id", // required: the constructor throws without it
  baseUrl: "https://api.arettic.com",
  // maxRetries, timeoutMs, fetch and userAgent work as on Arettic
});

import os

from arettic import AretticOrg

# Positional: key, then org id. With neither, ARETTIC_API_KEY and ARETTIC_ORG_ID are read;
# without an org id the constructor raises ValueError.
org = AretticOrg(os.environ["ARETTIC_ORG_KEY"], "your-org-id", base_url="https://api.arettic.com")

// A test agent. Its key is in the answer once; store it now.
const { agent, key } = await org.agents.create({ name: "research bot", mode: "test" });
console.log(key); // sk_test_…

// A $50 monthly budget, and ask an owner before any single purchase over $20.
await org.agents.update(agent.id, {
  monthly_budget_credits: 50_000,
  approval_threshold_credits: 20_000,
});

// Approve what is waiting.
for (const a of await org.approvals.list({ status: "pending" })) {
  await org.approvals.decide(a.approval_id, { decision: "approve", note: "ok" });
}

// September's receipts, page by page, then the same month as CSV.
const month = { from: "2026-09-01", to: "2026-09-30" };
let page = await org.receipts.list({ ...month, limit: 50 });
const receipts = [...page.receipts];
while (page.next) {
  page = await org.receipts.list({ ...month, before: page.next });
  receipts.push(...page.receipts);
}
const csv = await org.receipts.exportCsv(month);

// A webhook for finished jobs and decided disputes. The secret is shown once.
const { webhook } = await org.webhooks.create({
  url: "https://agent.example.com/arettic",
  events: ["job.completed", "dispute.decided"],
});
console.log(webhook.secret);

# A test agent. Its key is in the answer once; store it now.
made = org.agents.create(name="research bot", mode="test")
print(made["key"])  # sk_test_…

# A $50 monthly budget, and ask an owner before any single purchase over $20.
org.agents.update(made["agent"]["id"], monthly_budget_credits=50_000, approval_threshold_credits=20_000)

# Approve what is waiting.
for a in org.approvals.list(status="pending")["approvals"]:
    org.approvals.decide(a["approval_id"], "approve", note="ok")

# September's receipts, page by page, then the same month as CSV.
month = {"from_": "2026-09-01", "to": "2026-09-30"}
page = org.receipts.list(limit=50, **month)
receipts = list(page["receipts"])
while page["next"]:
    page = org.receipts.list(before=page["next"], **month)
    receipts.extend(page["receipts"])
csv_text = org.receipts.export_csv(from_="2026-09-01", to="2026-09-30")

# A webhook for finished jobs and decided disputes. The secret is shown once.
hook = org.webhooks.create("https://agent.example.com/arettic", events=["job.completed", "dispute.decided"])
print(hook["webhook"]["secret"])

curl https://api.arettic.com/v1/execute \
  -H "Authorization: Bearer $ARETTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "User-Agent: arettic-sdk-ts/0.1.0" \
  -d '{
    "tool_id": "mock-verify-email",
    "input": { "email": "[email protected]" },
    "idempotency_key": "b3b0d3a2-6d5e-4f1a-9c2b-7e8f9a0b1c2d"
  }'

{
  "status": "declined",
  "error": {
    "code": "insufficient_credits",
    "message": "This needs 7 credits ($0.007); the org has 0 ($0.000). Top up to continue.",
    "doc_url": "https://arettic.com/docs/errors#insufficient_credits",
    "retryable": false
  }
}

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

try {
  await arettic.execute({
    tool_id: "mock-find-email",
    input: { first_name: "Emily", last_name: "Carter", domain: "acme.com" },
  });
} catch (err) {
  if (!(err instanceof AretticApiError)) throw err;
  console.error(err.status, err.code, err.message, err.docUrl);
  if (err.code === "insufficient_credits") {
    // 402, not retryable: top up, or lower max_price.
  } else if (err.retryable) {
    // A read or an execute was already retried. A plain POST like recommend was sent once:
    // wait err.retryAfter seconds (or a moment) and send it again yourself.
  }
}

from arettic import AretticApiError

try:
    client.execute(
        tool_id="mock-find-email",
        input={"first_name": "Emily", "last_name": "Carter", "domain": "acme.com"},
    )
except AretticApiError as err:
    print(err.status, err.code, err.message, err.doc_url)
    if err.code == "insufficient_credits":
        ...  # 402, not retryable: top up, or lower max_price.
    elif err.retryable:
        ...  # a read or an execute was already retried; a plain POST you send again yourself,
        # after err.retry_after seconds when it is set

await arettic.execute(
  { tool_id: toolId, input: { email: "[email protected]" } },
  { idempotencyKey: "order-42-verify" },
);

client.execute({"tool_id": tool_id, "input": {"email": "[email protected]"}}, idempotency_key="order-42-verify")

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

const arettic = new Arettic({ apiKey: process.env.ARETTIC_API_KEY, baseUrl: "https://api.arettic.com" });

async function main() {
  // 1. Which tool works for this task? The rank ignores whether you can buy, so take the first purchasable one.
  const { options } = await arettic.recommend({ task_type: "verify_email", region: "US" });
  const tool = options.find((o) => o.purchasable);
  if (!tool) throw new Error("No purchasable tool for verify_email");

  // 2. Buy one result.
  const request = { tool_id: tool.tool_id, input: { email: "[email protected]" } };
  let bought = await arettic.execute(request);

  // 3. Over the approval threshold? Wait for an owner, then send the same request with approval_id.
  if (bought.status === "approval_required") {
    const approval = await arettic.waitForApproval(bought.approval_id);
    if (approval.status !== "approved") throw new Error("Approval " + approval.status);
    bought = await arettic.execute({ ...request, approval_id: approval.approval_id });
  }

  // 4. Read the answer.
  switch (bought.status) {
    case "passed":
    case "partial":
      console.log(bought.result, bought.charged); // live: { credits: "7", usd: "0.007" }; test: "0"
      break;
    case "failed":
      console.log("Not charged:", bought.reason);
      break;
    case "queued": // only when inputs has more than 25 items
      console.log(await arettic.waitForJob(bought.job_id));
      break;
  }

  // 5. A live key gets a receipt. Something wrong with a charged item? Dispute it within 7 days.
  if ("receipt_id" in bought) {
    const receipt = await arettic.receipt(bought.receipt_id);
    console.log(receipt.items[0]?.provider, receipt.items[0]?.outcome, receipt.check_version);
    // await arettic.openDispute({ receipt_id: receipt.receipt_id, item_index: 0, reason: "wrong_result" });
  }

  console.log(await arettic.balance()); // the org's credits, and this agent's spend and budget
}

main().catch((err) => {
  if (err instanceof AretticApiError) console.error(err.status, err.code, err.message);
  else console.error(err);
  process.exit(1);
});

import os
import time

from arettic import Arettic, AretticApiError

client = Arettic(api_key=os.environ["ARETTIC_API_KEY"], base_url="https://api.arettic.com")


def main() -> None:
    # 1. Which tool works for this task? The rank ignores whether you can buy, so take the first purchasable one.
    rec = client.recommend(task_type="verify_email", region="US")
    tool_id = next(o["tool_id"] for o in rec["options"] if o["purchasable"])

    # 2. Buy one result.
    request = {"tool_id": tool_id, "input": {"email": "[email protected]"}}
    bought = client.execute(request)

    # 3. Over the approval threshold? Wait for an owner, then send the same request with approval_id.
    if bought["status"] == "approval_required":
        approval = client.approval(bought["approval_id"])
        while approval["status"] == "pending":
            time.sleep(5)
            approval = client.approval(bought["approval_id"])
        if approval["status"] != "approved":
            raise RuntimeError("Approval " + approval["status"])
        bought = client.execute({**request, "approval_id": approval["approval_id"]})

    # 4. Read the answer.
    status = bought["status"]
    if status in ("passed", "partial"):
        print(bought["result"], bought["charged"])  # live: {"credits": "7", "usd": "0.007"}; test: "0"
    elif status == "failed":
        print("Not charged:", bought["reason"])
    elif status == "queued":  # only when inputs has more than 25 items
        print(client.wait_for_job(bought["job_id"]))

    # 5. A live key gets a receipt. Something wrong with a charged item? Dispute it within 7 days.
    if "receipt_id" in bought:
        receipt = client.receipt(bought["receipt_id"])
        item = receipt["items"][0]
        print(item["provider"], item["outcome"], receipt["check_version"])
        # client.open_dispute(receipt_id=receipt["receipt_id"], item_index=0, reason="wrong_result")

    print(client.balance())  # the org's credits, and this agent's spend and budget


if __name__ == "__main__":
    try:
        main()
    except AretticApiError as err:
        raise SystemExit(f"{err.status} {err.code}: {err.message}")

{
  "org_balance": {
    "paid": { "credits": "20000", "usd": "20.000" },
    "trial": { "credits": "993", "usd": "0.993" },
    "total": { "credits": "20993", "usd": "20.993" }
  },
  "agent_spent_month": { "credits": "7", "usd": "0.007" },
  "agent_budget": { "credits": "50000", "usd": "50.000" },
  "agent_budget_left": { "credits": "49993", "usd": "49.993" }
}