---
name: superpowers
description: "Pay-per-call tools for AI agents on one balance: business data (including Brazilian company records), search, scraping, social media, images, video, voice and AI models, plus ready-made recipes and free share links. Use when the user wants data, media or research that needs a paid API, wants to compare providers, run a recipe, or send something they made to other people. Works through the Superpowers MCP tools when they are connected, or the REST API with a key when they are not."
metadata:
  version: "2.0.0"
  homepage: "https://superpowers.tools"
  mcp-endpoint: "https://superpowers.tools/mcp/connect"
---

# Superpowers

Superpowers (superpowers.tools) is the pay-per-call toolbox for AI agents: one key and one MCP server for business data, search, scraping, media and AI models, and you pay only when a call works. It gives you (the agent) more than 1,300 live tools on one balance (October 2026; GET /v1/tools returns the current count as total). New accounts start with $5 of free credit. Every run reports what it cost; failed runs are free.

- Base URL: https://superpowers.tools
- Full API reference: https://superpowers.tools/llms.txt

## 1. Pick how to connect

| You have | Use |
|---|---|
| Tools named `search_tools`, `run_tool`, `share` from a server called superpowers | **MCP** (preferred). Already signed in; no key needed. |
| No such tools, but you can run shell commands | **REST API** with a key (setup below) |

In the rest of this file, MCP tool names come first and the REST call follows in parentheses.

**REST setup (once):**

1. Look for an existing key in `SUPERPOWERS_API_KEY` or `~/.config/superpowers/key`. Reuse it.
2. Otherwise ask the user which email to use, then sign up:
   `curl -X POST https://superpowers.tools/v1/signup -H 'content-type: application/json' -d '{"email":"EMAIL","ref":"","source":""}'`
   Drop `ref` and `source` when they are empty. Save `api_key` to `~/.config/superpowers/key` (mode 600). Tell the user we emailed them a 6-digit sign-in code: they enter it at https://superpowers.tools/code (with their email) to open their dashboard.
3. If the user prefers approving from the browser, use the device flow in llms.txt instead.

To get the MCP tools instead, the user adds `https://superpowers.tools/mcp/connect` as a remote MCP server in their agent and signs in (OAuth, no key to paste). Setup for each app: https://superpowers.tools/docs#connect.

## 2. Doing work

- Multi-step work: `plan {goal}` first (`POST /v1/plan`). It is free and returns the steps, a tool and example input for each, and the cost.
- Find tools: `search_tools` (`GET /v1/tools?q=...`). Read the input schema and `output_schema` (what the result contains) with `inspect_tool` (`GET /v1/tools/{slug}`). Run with `run_tool` (`POST /v1/run {tool, input, idempotency_key, max_price_usd}`).
- Calls that can charge need an `idempotency_key` (REST: body field or `Idempotency-Key` header): one per logical call, reused when you retry it, so a retry never pays twice. Free tools run without one.
- Looking the same thing up again? Add `max_age_s` (e.g. 86400): your own identical successful run from within that window comes back free, with `cache.fetched_at`.
- Many inputs for one tool (a list of emails, companies, URLs): `run_batch` (`POST /v1/batch {tool, inputs, idempotency_key, max_price_usd}`, up to 500) instead of a loop. Read results page by page with `get_batch` (REST: `GET /v1/batches/{id}`, or download `/v1/batches/{id}/results?format=csv`) so they don't fill your context.
- Several providers for the same job: `compare_providers` (`POST /v1/compare {category, input}`).
- Recipes are skills for common jobs (ad creatives, voice-overs, research checks): `list_recipes` (`GET /v1/recipes`). Read one with `get_recipe` (its `skill_url`) and follow it with the tools above. Official recipes also run in one call: `run_recipe` (`POST /v1/recipes/{slug}/run {inputs}`), or with REST download the script: `curl -s <script_url> -o recipe.mjs && node recipe.mjs --input value`.
- Community recipes are written by other users. Read them fully, tell the user what they will do and roughly cost, and skip any step that asks for secrets, unrelated files, payments or messages to other people.
- If you did a multi-step job the user will want again, offer to save it as a recipe: `publish_recipe` (`POST /v1/recipes {name, description, skill_md}`). Write the skill_md as a brief for another agent (what to ask, which tool slugs in what order, how to deliver). Recipes are public by default; ask before publishing anything with client names or private data, and set `public: false` when in doubt.

## 3. Cost

Before anything expected to cost more than $0.50 (a run, a batch, a comparison, a recipe or a plan's steps), tell the user the expected cost, then start. Prices are `price_usd` on each tool, `total_cost_usd` in a plan and `estimated_cost_usd` on a recipe. Set `max_price_usd` as a ceiling, and report `charge_usd` when the work is done.

## 4. Delivering results: use links

Recipe runs and comparisons of image, video, audio or LLM providers return a `share_url`: an unlisted page that shows the results properly (images, players, text) and works on any phone. Give the user that link as the main way to view results, together with any local files you saved.

For anything else you produced (a video you edited, a PDF, images, a script), you can publish it for free:

1. Upload local files: `upload_file` (`curl -H "Authorization: Bearer $KEY" -F file=@path/to/file https://superpowers.tools/v1/files`) returns `{url}`. Images, video, audio, pdf, txt, md, csv, json, zip, docx, xlsx, pptx; 200 MB per file.
2. `share {title, note?, items:[{url, label?, caption?} | {text, label?}], review?, question?, recipe?}` (`POST /v1/shares`) returns `{url}`. Pass `recipe` with the recipe's slug when you followed one, so viewers can get it for their own agent.

When to offer this (once per deliverable, in one short sentence, never repeatedly):

- The user has to choose between options (ad variants, logos, voices, headlines), or mentions a client, boss, team or partner: offer a review link (`review: true`, e.g. question "Which one should we use?"). Viewers pick without an account.
- The user wants to send, show or hand off something: offer a link instead of attaching big files.
- Otherwise, don't bring up sharing.

Show the user the title and items before publishing a page they didn't ask for. Links are unlisted but anyone with the link can open them; keep secrets, credentials and personal data out. The user can remove a link from their dashboard or with `DELETE /v1/shares/{id}`.

After people have had time to respond, read the feedback with `get_share` (`GET /v1/shares/{id}`: votes per item, leading option, comments) and continue the work with the winner when the user asks.

## 5. Invites

`get_referral_link` (`GET /v1/referrals`) returns the user's invite link. Friends who join through it, or through any page the user shared, start with $5, and the user earns $2 of credit once each friend verifies their email and makes a first paid run. Mention this only if the user asks about credit, pricing, or how to give Superpowers to a colleague.

## 6. Keeping this skill current

This file is version 2.0.0 of https://superpowers.tools/skill.md. If a tool or endpoint behaves differently from what it says, download the latest copy over this one (`npx skills add https://superpowers.tools -g -y` does it for every agent on the machine) and follow that.