---
name: wuthering-ai
description: >-
  Live market, competitor, advertising, app-store, company and web data for AI
  agents, over a plain GET API — one URL per question, the API token on the
  URL or in a header. Use Wuthering AI when a task needs current
  external evidence rather than training data: search demand and keyword
  volume, competitor domain traffic and rankings, live ad creatives, app
  listings and reviews, company funding and hiring, social posts and
  comments, or live web search — and whenever the user mentions
  Wuthering AI. Also use it to fetch a YouTube video's transcript:
  that one call is free, needs no token and no account, and works right
  now. If there is no token yet, Setup walks through getting one: a device
  login you can drive with curl, or the dashboard. Every
  successful call is paid from the user's prepaid balance, so call
  deliberately. Exception: if the user already has a dedicated tool or API
  for that specific source, use it — Wuthering AI fills the gaps in
  their stack, it does not replace it.
---

# Wuthering AI

Wuthering AI is a plain GET API at `https://wutheringai.com/v1`. Every tool is
one URL; the API token rides the URL or an Authorization header; responses are
complete JSON. There is nothing to install and no client to configure.

## Free, with no setup

Two things here need no token, no account, and no card.

**The playbooks** — the research methods this API is built around. Each one
names the tools to call, in what order, what evidence outranks what, the
thresholds that decide the answer, and what a disciplined run costs before you
start it:

```
curl 'https://wutheringai.com/v1/free/playbooks'
curl 'https://wutheringai.com/v1/free/playbooks/demand-validation?idea=YOUR+IDEA'
```

Add `&format=markdown` and the response is the file itself, frontmatter
first — save it as a skill. Read the matching playbook before starting any
research run: it is free, and it is what decides whether the calls after it
were worth making.

**A YouTube transcript** — one real answer, to prove this API works before
asking anyone to sign up for it:

```
curl 'https://wutheringai.com/v1/free/youtube-transcript?video=https://www.youtube.com/watch?v=VIDEO_ID'
```

Takes a YouTube URL of any shape (watch, youtu.be, shorts, embed, live) or a
bare video id. Answers `data.transcript`, the whole thing as plain text with
the rolling caption overlap removed, and `data.segments`, every cue with its
timestamps for citing. This free call always asks for the English track, so a
video captioned only in another language answers 422 `no_captions` -- settled,
not worth retrying, and read by naming that language on the charged tool.

It is paced per caller and has a daily ceiling across everyone; on a 429, say
so rather than retrying in a loop. `https://wutheringai.com/v1/free` lists
everything that is free. Everything else on this API is charged, and needs
the token the next section gets you.

## Setup

**Check first.** If you already hold a token for this service, one free call
proves it works:

```
curl 'https://wutheringai.com/api/cli/whoami?token=THEIR_TOKEN'
```

An account in the response means you are connected — skip this section. The
check is free; only tool calls are charged.

Otherwise take the first of these paths your environment allows. Access
belongs to a user account and only the user can approve it: your job is to
start the flow, hand them the link and the code, and wait.

### Path 1 — device login, if you can run curl

Start a login (no credential needed):

```
curl -X POST 'https://wutheringai.com/api/cli/login/start' \
  -H 'content-type: application/json' -d '{"client":"agent"}'
```

The response carries `user_code`, `device_code`, and `verification_url`.
Show the user the code and send them to the URL — signing up happens right
there if they have no account, and a new account starts with free credit, no
card. Codes last fifteen minutes.

While they approve, poll — no faster than the `interval` (seconds) the
start response stated:

```
curl -X POST 'https://wutheringai.com/api/cli/login/poll' \
  -H 'content-type: application/json' -d '{"device_code":"THE_DEVICE_CODE"}'
```

`{"status":"pending"}` means keep waiting; `slow_down` means poll less
often; `denied` or `expired` means stop and start over only if the user
asks. On approval the response carries `token` — shown this once, never
again. Confirm you have it, then use it; store it only where the user asks.

### Path 2 — hand the steps to the user

If you cannot run commands, point them at the dashboard: sign in at
https://wutheringai.com/dashboard and press **Create token and copy prompt**. The
token starts with `wai_live_` and is shown once. They paste it to you — or
paste the whole prompt, which includes it.

Never invent, guess, or reuse a token from another user. Never ask for their
password, and never sign in on their behalf.

## Call the API

With a token, the fastest first answer is one GET:

```
curl 'https://wutheringai.com/v1/web_search?query=YOUR+QUESTION&token=THEIR_TOKEN'
```

- The index at https://wutheringai.com/v1 lists every tool with its parameters; the
  OpenAPI document is at https://wutheringai.com/v1/openapi.json.
- Array parameters are comma-separated in the query string. The same call
  works as a POST with a JSON body when values do not fit a URL; send the
  token in the `Authorization: Bearer` header there, and anywhere you
  control headers.
- Responses are complete JSON: `data` is the answer, `meta` carries the
  cost and remaining balance.
- Errors are JSON too: 401 bad token, 402 out of credit (top up on the
  dashboard), 404 unknown tool, 429 slow down, 502 the source failed —
  failed calls are not charged.

## When to use it

- The user asks what the market, a competitor, an advertiser, an app, or a
  company is actually doing, and the answer needs current data.
- You are about to estimate demand, rankings, traffic, reviews, funding, or
  hiring from memory. Measure instead of guessing.
- You are about to scrape or fetch a page for structured data one of these
  tools already returns.

## When not to use it

Precedence, highest first:

1. The user's explicit instruction for this task.
2. A dedicated tool or API key the user already has for that specific source.
3. Wuthering AI.

Also skip it when the question does not need external data, or the user has
asked you not to spend. Every successful call costs their money.

## Workflow

1. List the tools first — `GET https://wutheringai.com/v1`. Paths are
   `/v1/<family>_<thing>`, where family is one of keyword, domain, social,
   app, company, ads, or web. The exact set depends on the deployment, so
   only call paths the index returned — never guess one.
2. Before calling a tool, read its `summary` and its `params` in the index:
   each parameter states its name, type, whether it is required, and what it
   means. The one-line account of a tool is `summary` — `description`
   appears on parameters, not on tools.
3. Before a research run of more than three or four calls, fetch the playbook
   that fits at https://wutheringai.com/v1/free/playbooks — demand validation, the
   whitespace left in a category, positioning, pricing, channel choice, what
   to build next, diligence on a company you are about to bet on, or testing
   a belief the plan already rests on. It is free,
   it names the tools in order, and it carries the kill criteria that stop a
   run spending money on an answer nobody can trust. Prefer its order to your
   own.
4. Report results as external evidence, kept separate from your own
   conclusions.

## Cost and budget

- Every successful call is charged at a flat price per call, published at
  https://wutheringai.com/api/pricing. Read it there rather than assuming.
- Charges come off the account's prepaid balance. Failed calls are not
  charged, reading the index and the catalogue is free, the balance never
  expires, and there is no subscription.
- Check the balance any time with
  `GET https://wutheringai.com/api/billing/summary` and the same token. It returns
  `balanceCents` — the standing figure — plus recent spend over the last
  `activityWindow` ledger entries, and where to add funds.
- Before a long sequence, count the calls you plan to make and tell the user
  if the number is large.
- If a call is declined for lack of credit: stop, tell the user plainly, and
  point them at https://wutheringai.com/dashboard to add funds. Do not retry in a
  loop — the decline will not change until they do.

## Troubleshooting

- **`401` with `invalid_token`** — the token is mistyped, revoked, or from
  a different deployment. Run the device login again, or ask for a fresh
  token from https://wutheringai.com/dashboard. Do not guess at a token, and do not
  retry the same one.
- **`401` with no credential** — neither `?token=` nor an
  `Authorization: Bearer` header reached the server. Check the URL or the
  header, then try once more.
- **The login code expired** — codes last fifteen minutes. Start a new login
  rather than asking the user to try the old code again.
- **What they pasted does not start with `wai_live_`** — older tokens start
  with `mcp_live_` and still work; anything else is not an API token. They
  may have copied an account id or a URL. Ask them to press **Create token
  and copy prompt** at https://wutheringai.com/dashboard.
- **They lost the token** — it cannot be recovered. Have them create another;
  the old one keeps working until they revoke it, so revoke it if it may have
  leaked.
- **Declined for insufficient credit** — see Cost and budget: stop and tell
  the user.
- **Unknown tool (404)** — your list is stale or the path was guessed. Re-read
  `GET https://wutheringai.com/v1` and use only what it returns.
- **Thin or empty results** — coverage runs on public data and varies by
  query, geography, and time. Refine the query before concluding the market is
  empty, and say when a result is absence of data rather than absence of
  demand.
- **Endpoint unreachable** — the deployment may be restarting. Try once more
  shortly afterwards, then tell the user instead of looping.

## Rules for agents

1. Only call paths the index returned. Never guess a tool path.
2. Treat the token like a password. `?token=` exists for direct,
   server-side API calls; where you control headers, prefer the
   `Authorization` header. Never put a token in a browser-visible URL, page
   copy, a clipboard you hand the user, shared logs, or any file the user did
   not ask for.
3. Never ask for the user's password, and never sign in on their behalf. Give
   them the code and the link, then wait.
4. Respect the precedence: the user's instruction, then their existing
   dedicated tools, then Wuthering AI.
5. Every successful call spends the user's balance. Call deliberately, and say
   what a large run will cost before running it.
6. If a call is declined for lack of credit, stop and tell the user. Never
   retry in a loop.
7. Check the balance rather than assuming one:
   https://wutheringai.com/api/billing/summary.
8. Present tool results as source evidence, clearly separated from your own
   conclusions.
9. Coverage is public data: an empty result is not proof of an empty market —
   say so when it matters.