treg

# treg — the tool catalog for your agent **Ask for the task, not the tool.** When a job needs external or live data — backlinks, keyword volume, a TikTok profile, a work email, competitor ad creative — search the catalog, read the price, call it. Two kinds of tool answer to the same token, through the same proxy, which injects the credential **server-side** so you never hold it: - **The catalog** — curated external endpoints treg can call for you. - **Your own tools** — what a teammate registered and shared with this org: API accounts, OAuth connections, skills. Note: an X (Twitter) connection made through treg's app is metered per call (X bills the app owner per use); the response reports the price. A team's own X developer app is not metered. The mechanics: - **Endpoint:** `{BASE}` · **CLI:** `treg` · the CLI is a thin client over the API. - **Auth:** every call sends `X-Treg-Token: <your token>`. - A **tool** = an upstream base URL + credential **bindings**. A **skill/bundle** = a recipe (SKILL.md) + its secrets + its tool(s). The proxy *relays, never models* the upstream. New verified accounts receive $1.00 of signup credit once, when creating an eligible team. Additional teams start with no signup credit, and aliases of one inbox (`+tag`, Gmail dots) share a single credit. Legacy `POST /users` registration does not verify an email, so its team starts at zero and receives the credit when you first sign in with email OTP or Google/GitHub. Existing balances remain usable. ## First: install + sign in ```bash curl -fsSL {BASE}/install.sh | sh # installs the CLI + points it here treg login # browser sign-in (GitHub / Google / email code) — first login registers you treg login --email you@company.com # emailed 6-digit code (falls back to the browser if the server requires a browser check) treg login --token <per-org-token> # non-interactive (agents/CI) ``` Everything runs in your **active org** (after first login, create or join a team). Team invites arrive by email — see them with `treg invites`, accept with `treg accept` (or `treg org join <code>`). Switch teams: `treg org use <slug>`. ## Already connected over MCP? Then you have the tools, not the CLI If you reached treg through `{BASE}/mcp/` — ChatGPT, Claude Code, Cursor — the CLI steps above do not apply to you. You have `catalog_search`, `catalog_get`, `call`, `call_media`, `resources_list`, `balance`, `my_tools`, `catalog_request`, `feedback`, and `review`. Everything in this document maps onto them: - "search the catalog" → `catalog_search`, then `catalog_get` for the exact price and parameters. Its `verdict` says what you got: `strong` (these do the job, every provider of it by measured success), `closest` (nearest, check `catalog_get`), `none` (not in the catalog: file `catalog_request`, do not rephrase), `keyword` (ranked by words alone) - "what's new" → `catalog_search` with `added_within_days` (30 is a good default) or `sort: "newest"`; `query` may be empty. - "call it" → `call` with the endpoint id, or `<tool-name>/<path>` for one of the team's own tools - "check the balance" → `balance` - "share feedback" → `feedback` The rules below are the same either way. The one that matters most — **say the price before you spend it** — matters more here, because `call` returns `cost_usd` and you can report what a call actually cost rather than estimating. A `call` on a catalog endpoint spends the team's balance. A `call` on one of the team's own tools spends nothing: that key belongs to them. ## Task — the catalog: what treg can do for you (start here) {ENDPOINTS} catalogued endpoints across {PROVIDERS} providers, grouped by what they DO: keyword & rank tracking, backlinks & authority, AI visibility, trending & discovery, publishing to the team's own social accounts, people & company enrichment, ads management & creative, measurement, video & image generation. ```bash treg catalog search "subreddit posts" # find endpoints by what they do treg catalog search --new # tools added in the last 30 days, newest first treg catalog get scrapecreators.reddit.subreddit.posts # params, PRICE, how you'd be served treg call scrapecreators.reddit.subreddit.posts --query subreddit=news treg balance # the prepaid balance + recent charges treg catalog request "<what you need>" # searched, not there? file it — steers what's added next ``` Notes: - Every endpoint's price is in `treg catalog get`, before you call it. - Search for the job AND any output you need: `treg catalog search "email verification catch-all"` finds different tools from a broad email-verification search. Check each candidate with `treg catalog get` for its fields, parameters and price before choosing. If you need a provider's catch-all, disposable, role-address or SMTP field, call that provider's endpoint: the routed `treg.people.email.verify` contract defines only `valid`, `status` and `score`. - To find AND check an email in one call, send `--header "X-Treg-Route-Verify: true"` on `treg.people.email.find`. The check is its own small charge. Read `_treg.verification.verdict` (`valid`, `invalid`, `catch_all`, `risky`, `unknown`); `checked: false` means no check ran. The same header on `treg.people.phone.find` checks the line live: `live`, `dead` or `unknown`. Never call a phone "verified": a live line is not proof it is this person's number. - A catalog endpoint can use a verified public route with no provider key. Such a call is free when the caller does not send a provider credential. The team tool or stored provider key still wins. - Discovery jobs usually have TWO shapes in the catalog — a structured one (filters: title, location, followers, funding) and a semantic one (describe what you want; `exa.*`). When a brief mixes hard limits with a fuzzy niche, run both and merge: e.g. creators = `influencersclub.creators.search` (filters) ∪ `exa.creators.search` (description, pinned to the platform domain); people = a `people.search` provider ∪ `exa.people.search`; who-holds-a-role questions = `exa.web.answer`. - HTTP **402** = out of balance, with a machine-actionable body (`balance_micro`, `estimated_cost_micro`, `topup_url`). Recovery: `treg balance` → top up in the dashboard (Team → Billing) → or store the org's own key for that provider (own keys are never billed to the balance — they take priority automatically). A 402 with `error: route_max_cost` is different: YOUR `X-Treg-Route-Max-Cost` header refused the call before anything was charged — ask for fewer rows/targets or raise the ceiling. - **Body from a file:** `treg call <id> --data @body.json` (`@-` reads stdin). On Windows PowerShell prefer it to inline JSON, whose inner quotes PowerShell strips. - **Scripting many calls:** use `treg --json call …`. Stdout is one line, `{"result": <provider body>, "_treg": {"http_status", "call_id", "charged_micro"}}`, and nothing goes to stderr, so a script that merges the streams still parses every answer (`--await` output is unchanged). Run a handful and check the parsed results before looping over the whole list: a parse bug throws away answers that were already billed. - The real charge is the response header `X-Treg-Cost-Micro` (micro-USD), with `X-Treg-Call-Id` as the id to quote. An idempotent replay reports `0` there and the first call's charge in `X-Treg-Original-Cost-Micro`. Lost an answer you paid for? `GET /calls/<call id>/result` returns the stored response of a successful catalog call. On an asynchronous submission that header is the reserved ceiling; the CLI labels it as a reservation, and the terminal task settles the real charge. The catalog `~$/call` figure for a `per_result` route assumes a 20-row page when the price is per row; when the catalog `cost.unit` is `target`/`domain`/`keyword` you pay per thing asked about, one unit per target. Failed calls (4xx/5xx relayed from the provider) are free; empty results mean whatever the provider means by them — treg relays, it does not normalise. A provider that reports a failure inside a 2xx answer (a DataForSEO task status other than 20000) is flagged with `X-Treg-Upstream-Failed` (`upstream_failed` over MCP): the body has no result, and the charge is what the provider billed for the attempt. - A call may be answered from treg's archive of the exact same question while that answer is fresh: verbatim provider bytes, `X-Treg-Cache: hit`, `X-Treg-Fetched-At`, `X-Treg-Age`. Your team's first call on a question costs full price either way; from your second call on, a hit costs 10%, and a hit on your own key is free. `Cache-Control: no-cache` forces a live call; `X-Treg-Max-Age: <seconds>` accepts only a younger answer. A team admin can opt the team out of the archive (`treg org archive off`): new calls are then neither answered from nor stored in it, so metered calls lose the repeat price. - HTTP **503** `provider_capacity_unavailable` = treg's own account for that provider is out (not your balance; nothing charged). Body has `resets_at` and `alternatives` (same capability, other providers) — choose one, or use your own key. treg never switches providers for you. treg re-checks the provider about once a minute, so a retry after a minute can succeed. - HTTP **503** `provider_paused` = this deployment paused that provider (nothing charged, nothing sent). Read `message`. The existing connection is kept; do not reconnect, it works again when resumed. - An org tool or secret for the provider always wins over an anonymous route or treg's key, automatically — the catalog is the fallback, not a replacement for keys the team already has. - **Choosing between providers of one capability — the procedure.** `treg catalog get <id>` lists every provider serving the same job with `COST`, `WORKS` (success rate treg has observed, with the sample size), `SPEED` (median) and `LAST OK`. Work down this order: 1. **Match the inputs you actually HAVE.** An endpoint wanting a `profile_url` is not a substitute when you hold a name and a domain, whatever it costs. This rule outranks price every time. 2. Then **reliability**: a high `WORKS` with a real sample beats a rounder number with a tiny one — `99% (121)` is stronger evidence than `100% (8)`. 3. Then **price**. Spreads inside one capability reach 200×, so this is usually where the money is. 4. `LAST OK` breaks ties. A bare age means a real call came back; a **`✓` age is the catalog's own verification stamp, not live traffic**; `—` means nobody has verified it and nobody has called it — prefer almost anything else. - **If a call fails with 429 / 5xx / a timeout, try the next provider.** You know its parameters, so you can build its request. Say which one you switched to. - **Never retry a 4xx elsewhere.** A 4xx is usually your parameters; fixing them is the fix, and retrying burns the team's money on N providers for one mistake. - treg does **not** choose or fail over **between providers** for you. That is deliberate: only you know which inputs you hold, and treg relays rather than rewrites your request. If treg's own account for a provider is out it may serve the **same endpoint** through a treg-owned relay (`X-Treg-Served-Via: overflow:<name>`, or `served_via` + a hint on the MCP `call` result; real price, same shape). `catalog_get` shows that price up front as `overflow_price_usd` when the deployment can relay the endpoint - a "free" endpoint with one may bill exactly that, so quote it. A team opts out with `treg org overflow off`. <!--hub--> - **Six jobs are already built as tools. Call the tool, not the chain.** Each is one call on `{BASE}/call/<id>`, runs the steps below in parallel, returns one fixed shape whichever provider answered, and charges its fee only for what it delivered. Chaining the endpoints yourself costs the same provider money and more calls, and the tool removes duplicates and stops at its budget for you. | you want | call | not this by hand | |---|---|---| | the people at a company, each with a checked email | `treg-hub.lead-pipeline` `{company_domain, title?, limit?, include_phone?}` | people.search → email.find → email.verify per person | | one person's email, found and checked | `treg-hub.verified-email` `{linkedin_url}` or `{full_name, domain}` | email.find → email.verify | | whether AI engines mention a brand | `treg-hub.ai-visibility` `{prompt, brand, brand_domain?, competitors?}` | ChatGPT, Gemini, Copilot, AI Mode one by one, then reading each answer | | company details you can trust | `treg-hub.company-consensus` `{domain}` | two or three companies.enrich providers, then comparing fields | | how strong a site is in Google | `treg-hub.domain-authority` `{domain}` | backlinks summary + ranked keywords + linking domains | | a Search Console property's health (own account) | `treg-hub.search-console-health` `{site}` | performance + sitemaps + url inspection | `catalog_get <id>` shows each one's inputs, output and price line. When the hub is off on this registry these ids answer 404: fall back to the routed endpoints below. <!--/hub--> <!--routed--> - **For a common job, call the routed tool, not a provider you remember.** Scraping a page (`treg.web.extract`), web search (`treg.web.search`), Google results (`treg.google.serp.organic`, `treg.google.serp.maps`), finding or verifying an email (`treg.people.email.find`, `treg.people.email.verify`) and most social profiles have a `treg.<capability>` tool. treg picks the provider (your own key first), falls back when one fails or misses, and charges only the answer it returns. A provider you used last week may not be the best choice today: prices and reliability change. Name a provider only when you need fields or options that only it has. - **Routed endpoints** (`treg.<capability>`, e.g. `treg.people.email.find`) are where you can ask treg to choose: POST the identity (`{full_name, domain}` | `{first_name, last_name, domain}` | `{linkedin_url}`); treg runs the best child (own keys first, then cheapest per hit), falls back on errors AND misses (cheapest first, within `X-Treg-Route-Max-Cost`, default $1; a miss can be billed, so a routed row quotes `usd_per_call: null`, not $0 — set the header for bulk runs), and returns `{output, raw, _treg.served_by, _treg.tried}` + `X-Treg-Served-By`. `X-Treg-Route-Waterfall: 0` stops at the first miss. A filter a provider cannot apply (`country` on a name-only search) is still sent to the others, and the answer names it in `X-Treg-Ignored-Filters` / `_treg.ignored_filters` — post-filter, or send `X-Treg-Route-Strict-Filters: 1` to get a 422 (unbilled) instead of a looser answer. `catalog_get treg.people.email.find` shows the plan and prices. An async child is submitted and polled internally for up to 60 seconds. If it is still running, treg returns HTTP 202 with `_treg.outcome: pending`, its call reference and poll descriptor, `reserved_micro`, and `charged_micro: null`; do not retry or start another provider, because the existing task may still complete and charge. - **A found contact is not a confirmed one.** An email or phone find returns the provider's best match; only `output.verified: true` means it checked the mailbox. When it is not, the answer carries `_treg.advice` naming the verify step (`treg.people.email.verify`, a fraction of a cent) — run it before outreach, and never re-send the same find: every hit bills, repeats included. <!--hub--> `treg-hub.verified-email` does find + verify in one call and bills its fee only on a usable email. <!--/hub--> - **Verify before you send. Every address, every time.** This includes rows from a company or domain search (`treg.people.search`, `hunter.companies.emails`, …): those are directory listings, and a row's email is unconfirmed unless that row's own verification field says otherwise. Treat `invalid` as dead and `accept_all` as risky. And never send to an address the provider did not return — if a domain search came back empty, `info@` is a guess, not a result. Live 2026-09-08: 73 of one team's 79 bounces were unverified rows and guesses that one $0.006 verify call each would have caught. <!--/routed--> - An endpoint with no published price is refused rather than served free; connect your own key. ## Task - generate video, images, voice, or music Generation models live in the catalog under the `video-gen`, `image-gen`, `voice-gen`, and `music-gen` platforms, one row per model per route, so the same model on two routes sits next to itself with both prices. Models are not interchangeable - you pick one; treg does not choose. ```bash treg catalog search "text to video" # every model, with prices treg catalog get minimax.video-gen.h3.generate # native params, model enum, price table, async descriptor treg call minimax.video-gen.h3.generate --await --timeout 900 --data '{"model":"MiniMax-H3-Max", "content":[{"type":"text","text":"A paper boat drifts across a quiet pond at sunrise."}], "resolution":"480P","duration":5,"ratio":"16:9"}' treg call minimax.voice-gen.voices.list --data '{"voice_type":"system"}' treg catalog get minimax.voice-gen.speech-2-8-turbo treg call minimax.voice-gen.speech-2-8-turbo --data '{"model":"speech-2.8-turbo", "text":"A calm voice can make a complex idea feel simple.","stream":false,"output_format":"url", "voice_setting":{"voice_id":"English_expressive_narrator","speed":1,"vol":1,"pitch":0}}' ``` How it works: - **Voice generation is synchronous.** MiniMax returns JSON containing a 24-hour audio URL. The