# AIsa

> The resource layer for AI agents: one MCP endpoint and one key for web search, SEO, social, finance, crypto, prediction markets, people and company data, and LLMs.

This is the setup guide for agents. Read it top to bottom; load "Optional" links only when the task needs them.

## 1. Connect

Pick the first option that applies. Run the command yourself; the user only approves the browser sign-in.

### A. Your client supports remote MCP and can open a browser (default)

Add a remote MCP server named `AIsa` with URL `https://mcp.aisa.one/mcp` (Streamable HTTP), using your client's own command or config file. Auth: browser OAuth, no key needed. In a chat app (Claude, ChatGPT), the user adds it as a custom connector in settings.

Adding the server does not always start sign-in. If no sign-in window opens, start it from the client's own MCP authentication entry (a menu, command, or connector button); if only the user can reach that entry, tell them where it is. Sign-in is the slow step, not the API. Before it starts, tell the user in one line that an AIsa sign-in window or card is about to open and to click **Allow** (one click if the browser is already signed in to AIsa). Do not call step 2 until the user says sign-in is done or the AIsa tools appear; calling it earlier only returns 401, so do not retry in a loop.

If the client must restart to load the server, tell the user and wait. If you cannot add the connector yourself (sandbox, permission denied), give the user the server name and URL above and wait. Do not fall back to another method.

### B. Your client supports remote MCP but has no browser (CI, SSH, container)

Same endpoint, with the header `Authorization: Bearer $AISA_API_KEY` set in your client's MCP config instead of browser sign-in.
If `AISA_API_KEY` is not set, ask the user to create a key at https://console.aisa.one/api-keys and set it in the environment; never ask them to paste it into chat. Never print, log, or commit the key.

### C. The client has no MCP support

Use the CLI: `npm install -g @aisa-one/cli && aisa login` (Node.js 18+). Guide: https://aisa.one/docs/get-started/cli.md

### D. Calling AIsa over HTTP from your own code

- LLMs, OpenAI-compatible: `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`)
- Data APIs: `https://api.aisa.one/apis/v1`
- Auth: `Authorization: Bearer $AISA_API_KEY`
- Exact paths and schemas: https://aisa.one/docs/api-reference

## 2. Verify

Make one free authenticated call on the interface you connected:

- MCP (A, B): call `account` (no arguments). If it is not in the tool list, call `use` with `{"operation_id": "account"}` instead. Returns the key, balance, and usage.
- CLI (C): `aisa balance`. (`aisa whoami` is local only and does not count.)
- HTTP (D): `GET https://api.aisa.one/v1/credits/balance` with the Bearer header returns 200 with the balance: a free protected call, the same check `aisa balance` makes. `GET /v1/models` is only a transport check; success on it or on other discovery does not prove authenticated business access.

AIsa is connected only when this call succeeds. A tool list or a 401 response does not count.

### Tell the user

In the user's language, this shape and no longer. If the user already named a task, give the first line and do the task instead.

```
AIsa is connected · balance ${balance.available_usd}[ · Go-to-Market wallet ${subscriptions.hive_gtm.balance_usd}]
Try:
- "Show @NASA's live profile on X" (under one cent)
- "{prompt}"
- "{prompt}"
```

Show the Go-to-Market wallet only when `subscriptions.hive_gtm.active` is true; it is a separate balance, so leaving it out makes the account look smaller. Keep the NASA line as is. Pick the other two prompts from different lines below; each one runs on tools AIsa has today. Fill each `{...}` from what you know about the user (their repo, site, company, or stack), or leave the example in. CLI (C): take the balance from `aisa balance`; HTTP (D): from the `/v1/credits/balance` response.

- Web research: "Find three news articles from this week about {topic}, with links."
- SEO: "Search volume and keyword difficulty for {keyword}, and the top 10 Google results."
- AI visibility: "How often does ChatGPT mention {brand} in US English answers, and which domains does it cite most?"
- Finance: "One-page brief on {ticker}: price now, latest earnings, recent insider trades."
- Agent mail: "Give this agent its own inbox and send me a test email."
- Go-to-Market, only when `account` shows an active subscription: "What are people on X and Reddit saying about {brand}?" or "VP-and-above growth leads at {company}, with work emails."

## 3. Use

CLI (C): the same flow is `aisa search`, `aisa schema`, `aisa quote`, then `aisa call`; see the CLI guide. HTTP (D): use the API reference. The MCP server (A, B) exposes these tools:

1. `search`: describe the task in plain words. Returns candidate tools with their exact name, arguments schema, and list price, plus a `session_id` to pass on every later call. Free.
2. `list_categories`: categories to narrow a search. Free.
3. `batch_get_schema` (older servers also list it as `get_details`): full contract for up to 20 tools: arguments schema, whether each is read-only, side effects, and known pitfalls. Free.
4. `batch_quote`: the exact price of up to 20 calls with the arguments you will run, before anything runs. Free.
5. `batch_use`: run up to 20 quoted calls; each reports what it actually cost. Billed per call.
6. `use`: the older single-call form, kept for existing clients. Billed per call.
7. `account`: the key, balance, Go-to-Market wallet, and usage for today, 7 days, and 30 days. Free. Servers that do not list it answer `use` with `{"operation_id": "account"}`.

Take tool names and arguments from `search` or `batch_get_schema`. Never invent them. Re-quote if the tools or arguments change.

## 4. Spending

- Free: docs, `GET /v1/models`, `GET /v1/credits/balance`, MCP `search`, `list_categories`, `batch_get_schema`, `batch_quote`, `account`, and CLI `aisa search`, `aisa schema`, `aisa quote`, `aisa balance`.
- Quote the exact calls before running them: MCP `batch_quote`, CLI `aisa quote --json`. Run only what you quoted; re-quote if the tools or arguments change. Neither `batch_use` nor `aisa call` takes a price cap.
- If the quote reports `auto_execute_eligible: true` (a small total), run it without asking, unless the user set a tighter limit or asked only for a quote.
- Otherwise, before the first such call, tell the user in one message what you plan to call, the quoted price, and a total budget for the task in USD. Wait for approval, then run calls within that budget without asking again. Ask again only if the task changes or the next call would exceed the remaining budget.
- For operations billed by rows or credits, also set the operation's own limit (for example `limit`) so the cost stays bounded.
- Do not retry a failed paid call without telling the user.

## 5. Errors

- `401` with `missing_api_key`: no key was sent. Without a key every route answers this, including unknown paths, `GET /v1/models` and `GET /v1/credits/balance`; only routes that can be paid per request through MPP answer `402` instead. `401` with `invalid_api_key`: the key is wrong, on every route. See the Errors page table. Redo step 1A or set the key.
- `402`: low balance, or the operation requires the Go-to-Market plan. The response says which and where to resolve it. Tell the user which one it is (top up the balance, or subscribe to the plan) with the link from the response; do not retry. Without any key, a `402` is the MPP challenge, not a balance problem: set the key.
- `429`: rate limited. Wait and retry with backoff. Details: https://aisa.one/docs/api-reference/rate-limits

## Docs

- [MCP catalogue](https://mcp.aisa.one/servers): live list of servers, modules, and tool counts.
- [Module endpoints](https://mcp.aisa.one/llms.txt): `https://mcp.aisa.one/{module}/mcp` lists one area's tools directly (`seo`, `sales`, `social`, `finance`, `search`, `mail`, `gtm`). `search` still reaches everything from any endpoint.
- [Technical docs index](https://aisa.one/docs/llms.txt): any docs page is available as Markdown by appending `.md` to its URL.

## Optional

- [Models](https://aisa.one/models): live model catalog and prices.
- [API catalog](https://aisa.one/api): every data API with pricing.
- [Pricing](https://aisa.one/pricing): plans and billing.
- [OpenAPI 3.1](https://aisa.one/openapi.yaml): very large; use it for code generation, not for reading.
- [Product overview](https://aisa.one/llms-full.txt): what AIsa is and when to use it. Not needed for setup.
Declared API contract: 3b7e1ad8cb07c71df35b4604e6290a6d7011efa7039608f35e88c85e9dd05308; immutable Docs revision: 13e96b8de86ad1cdc5b32e1e218a94ee28ec8cf1. Source freshness and publication readiness are assessed separately. [Pinned OpenAPI source](https://raw.githubusercontent.com/AIsa-team/docs/13e96b8de86ad1cdc5b32e1e218a94ee28ec8cf1/openapi.yaml); [Complete OpenAPI JSON](https://aisa.one/openapi.json); [Readable technical contracts](https://aisa.one/docs/llms-full.txt).
- [Agent Mail](https://aisa.one/api/agentmail): 62 endpoints.
- [Ahrefs](https://aisa.one/api/ahrefs): 2 endpoints.
- [Twitter](https://aisa.one/api/twitter-api): 36 endpoints.
- [Akta](https://aisa.one/api/akta): 6 endpoints.
- [Apollo](https://aisa.one/api/apollo): 54 endpoints.
- [Brave Answer](https://aisa.one/api/brave-answer): 1 endpoints.
- [Brave Search](https://aisa.one/api/brave-search): 15 endpoints.
- [BytePlus SearchInfinity (AI Web Search + Fetch)](https://aisa.one/api/byteplus-search): 2 endpoints.
- [CNPJá](https://aisa.one/api/cnpja): 1 endpoints.
- [CoinGecko](https://aisa.one/api/coingecko): 23 endpoints.
- [DataForSEO](https://aisa.one/api/dataforseo): 489 endpoints.
- [Duffel Flights](https://aisa.one/api/duffel-flights): 15 endpoints.
- [Duffel Stays](https://aisa.one/api/duffel-stays): 10 endpoints.
- [EDINET API](https://aisa.one/api/edinet-api): 2 endpoints.
- [Exa](https://aisa.one/api/exa): 7 endpoints.
- [Financial](https://aisa.one/api/financial-api): 23 endpoints.
- [Firecrawl](https://aisa.one/api/firecrawl): 12 endpoints.
- [foreplay](https://aisa.one/api/foreplay): 4 endpoints.
- [fred](https://aisa.one/api/fred): 35 endpoints.
- [Kalshi](https://aisa.one/api/kalshi): 4 endpoints.
- [OpenAI Chat API](https://aisa.one/api/models): 8 endpoints.
- [Open-Meteo](https://aisa.one/api/openmeteo): 12 endpoints.
- [Oxylabs Web Scraper — Push-Pull async (LLM sources)](https://aisa.one/api/oxylabs-llm-async): 4 endpoints.
- [Parallel.ai](https://aisa.one/api/parallel.ai): 21 endpoints.
- [Perplexity](https://aisa.one/api/perplexity-api): 4 endpoints.
- [Polymarket](https://aisa.one/api/polymarket): 93 endpoints.
- [Querit](https://aisa.one/api/querit): 1 endpoints.
- [Scholar](https://aisa.one/api/scholar-api): 4 endpoints.
- [Reddit](https://aisa.one/api/reddit-api): 24 endpoints.
- [Search](https://aisa.one/api/search-provider): 2 endpoints.
- [Semrush](https://aisa.one/api/semrush): 19 endpoints.
- [Similarweb](https://aisa.one/api/similarweb): 29 endpoints.
- [Tavily Search](https://aisa.one/api/tavily-search-api): 4 endpoints.
- [Douyin](https://aisa.one/api/tikhub-douyin): 954 endpoints.
- [WaveInflu](https://aisa.one/api/waveinflu): 3 endpoints.
- [YouTube](https://aisa.one/api/youtube-search-api): 3 endpoints.