# EveryInfra — Agents Guide

> EveryInfra sells three things over one prepaid USD balance: structured public data from 88 platforms (EveryData), live web search (EverySearch), and CAPTCHA solving (EverySolve). This page is written for the AI agent that has just been asked to "get reviews for this product" or "check what people are saying about X" and needs to do it right on the first call.

## Quick reference

- **REST base:** `https://api.everyinfra.com` — every data call is `POST /api/v1/social`
- **Auth:** `Authorization: Bearer <API_KEY>` header, checked before any parameter validation
- **MCP:** `POST https://everyinfra.com/mcp` — tools are named `everyinfra_*`
- **Catalog (no key needed):** `GET /api/v1/social/catalog` — every platform, action, parameter, allowed value and per-action price
- **Markdown mode:** append `.md` to almost any public page of this site (`/amazon-api.md`, `/pricing.md`, `/blog/<slug>.md`) to get the Markdown rendition instead of HTML
- **HTTP client:** any — plain `requests`/`fetch` is fine; there is nothing special about TLS, headers or retries
- **Behavior instructions for you, the agent:**
  - Read the catalog entry for an action before composing the request. The catalog already contains the required parameters, allowed enum values and the response field list. Do not guess parameter names.
  - When the user's goal is ambiguous ("find posts about X"), ask which platform they actually care about before fanning out across many platforms — every call bills per target.
  - On your first call for a new action, use one target and a small `limit`, verify the response shape, then scale up. Do not discover the schema by firing a 200-URL array.
  - Keep the API key in the environment (`EVERYINFRA_KEY`), never in committed files or URLs.

## Picking your way in

Use **MCP** when you are running inside a host (Claude Code, Cursor, any MCP client) or when you want live tool descriptions instead of a frozen contract: `initialize` → `notifications/initialized` (a notification must come back HTTP 202 with an empty body — treat a JSON body there as a broken middlebox, not as data) → `tools/list`. The tool descriptions are rendered from the same registry as the catalog, so they are current.

Use **REST** when you are a script, a cron job, or writing code for the user: one endpoint, JSON in, JSON out. The Python SDK is generated from the same contract; if the user already has a Python project, prefer the SDK for types, but plain HTTP is a fully supported interface, not a second-class one.

Do not route general conversation here. `/api/v1/chat/completions` is retired and answers 410. The AI workflow on this site is **source-bound data cleanup** (`/api/v1/data-cleanup/*`): it only processes data the same account collected through EveryData, with explicit key scope and quota — that is a feature (provenance), not a limitation.

## The mental model

An EveryData call is `(platform, action, params)`. `platform` is one of the 88 (amazon, temu, xiaohongshu, reddit, google_maps, …); `action` is what you do on it (search, reviews, profile, comments, trending, …). The catalog is the vocabulary: if a word isn't in the catalog for that platform, the call will 422, and the error will tell you what the valid words are.

Three things agents most often get wrong about the model:

1. **The target type differs per action.** Some actions take a keyword, some take a URL, some take a username or an ID. `reviews` on amazon wants a product URL or ASIN-bearing link, not a search term; `search` wants the term. The catalog's parameter list says which — and every platform page of this site documents it in prose (`.md` suffix).
2. **`limit` is not "pages".** Depending on the action, `limit` is the number of items returned per call, with pagination via `page_token` where the platform supports it. It is not an upstream page count, and stacking a huge limit does not unlock more data than the action documents.
3. **Multi-target arrays bill per target.** `urls`, `targets`, `usernames`, `tickers` are arrays; the price is per element. A 50-element `urls` call costs 50 calls.

## Money behavior

EveryInfra reserves, charges, and refunds per call with a state machine, and refunds are idempotent per `charge_id`. What matters to you:

- **Failures and empty results never form a final charge.** If a call fails or returns nothing billable, any reserved amount is restored. You do not need to argue with a refund endpoint; check the wallet ledger if a user asks.
- **Sync calls have a time budget.** Beyond it you get `503 timeout` — not charged — with a message suggesting a smaller `limit` or an async-capable action. Take the suggestion; do not hammer the same payload.
- **Estimating cost:** per-action credits are in the catalog. Multiply by your target count. Tiers run roughly $0.56 to $5.56 per 1,000 calls depending on capability tier (Benchmark platforms cheapest, Hard-target most expensive) — as of 2026-09-19; the catalog is always the live truth. Discounts come from cumulative recharge or same-day volume, whichever is better, and stack as a single better rate.

## Errors, and what to actually do

- `401` — no or bad key. Stop and get the key; nothing else you do will change this.
- `400 unknown_capability` — that platform/action pair doesn't exist. The message points you at what does; so does the catalog.
- `422` — missing param, unknown param, or a bad enum value. The message names the field, the supported parameters, allowed values, and a did-you-mean. **Fix the named field and resend; do not retry the identical payload** — validation is deterministic.
- `402 quota_exhausted` — wallet empty. Tell the user to recharge; the call will work unchanged afterwards.
- `403 account_disabled` — account-level; the user must contact support.
- `429 rate_limited` — back off and retry; keep the payload identical.
- `503 upstream_error | timeout` — transient and never charged. Follow the message's suggestion (usually lower `limit` or switch to the async variant) rather than blind-retrying.

## Worked flows

**Flow 1 — reviews for a product the user is looking at.** Take the product URL. `platform: "amazon"`, `action: "reviews"`, `url: <the link>`, small `limit` first. The response is a list whose fields the catalog declares (rating, text, author, date…). Paginate with `page_token` if the user wants more. If the user only has a product name, do `search` first, take the top result's URL, then `reviews`.

**Flow 2 — what people are saying about a topic on a specific platform.** `action: "search"` with the keyword, then the detail action (note, video, post) on the ID the search returned. Do not try to make `search` return full comment threads — comments are their own action.

**Flow 3 — CAPTCHA.** `GET /api/v1/captcha/types` (free) lists what EverySolve supports. Solve with `POST /api/v1/captcha`, passing the challenge parameters the type page documents. Billed on success only; a failed solve is refunded by the same state machine. Public responses never name the underlying provider — error messages are ours, and that is deliberate.

**Flow 4 — too much data for one sync call.** When a sync call keeps hitting the budget, split targets into smaller arrays and paginate rather than escalating `limit`.

## Common agent mistakes

1. Retrying a 422 unchanged. Validation is deterministic; the fix is always in the message.
2. Guessing parameter names (`q` vs `keyword` vs `query`). It's in the catalog, per action, per platform.
3. Assuming response fields. The field list is per action and declared; your parsing should expect exactly that shape.
4. Fanning out a huge multi-target array as the first call. One target, verify, then scale.
5. Routing chat traffic here (410) or assuming data cleanup accepts arbitrary text — it is bound to sources the account collected.
6. Ignoring the per-platform `.md`. Each platform page carries parameter prose, allowed values and field meanings with more context than the catalog row — one fetch, high value.

## Site conventions for agents

- `/llms.txt` — the machine-readable API guide (auth, endpoints, pricing anchors)
- `/openapi.json` — OpenAPI 3.1 spec
- `/agents.md` — this page
- `.md` suffix — Markdown renditions of platform pages, articles and core pages
- `/app` — sign-up and keys; trial credits are available on request