Superpowers

Free. Describe a goal in plain words (e.g. 'find coffee shops in Pinheiros and their Instagram followers'). Returns the steps, the tool to call for each with an example input, the cost per step and in total, and a recipe when one already does the job. Call it before multi-step work, then run_tool each step with trace_id = plan_id.

{
  "type": "object",
  "properties": {
    "goal": {
      "type": "string",
      "description": "What you want done, in plain words"
    }
  },
  "required": [
    "goal"
  ]
}

Find marketplace tools by describing what you need in plain words (e.g. 'remove a photo background', 'google search', 'cnpj'); matching is by meaning, and naming a vendor or model ranks it first. An empty query lists every live tool. Returns slugs, prices and quality stats, plus total and has_more. When has_more is true, call again with offset = next_offset. Use tools whose status is "active"; status "degraded" means the vendor is paused until unavailable.available_at, so pick another tool.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "default": 15,
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "minimum": 0
    }
  },
  "required": [
    "query"
  ]
}

Get a tool's input schema, price and category before running it.

{
  "type": "object",
  "properties": {
    "tool": {
      "type": "string"
    }
  },
  "required": [
    "tool"
  ]
}

Run one tool with JSON input. Charges your balance; failed runs are free. Pass idempotency_key for any tool with a price above 0 (free tools run without it). Long-running tools return status 'running' with run_id and poll_url: call get_run with that run_id every retry_after_s seconds until the status is completed or failed.

{
  "type": "object",
  "properties": {
    "tool": {
      "type": "string"
    },
    "input": {
      "type": "object"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Stable key for one logical operation (1-128 letters, digits, _ . : / -). Reuse it to retry the same request, so a retry returns the first result instead of charging twice; use a new key for new work. Required by compare_providers, run_job and run_tool on tools that can charge; free tools (price 0) run without it."
    },
    "max_price_usd": {
      "type": "number",
      "minimum": 0,
      "description": "Hard total buyer charge ceiling, including all job/comparison steps."
    },
    "project_id": {
      "type": "string"
    },
    "agent_id": {
      "type": "string"
    },
    "trace_id": {
      "type": "string"
    }
  },
  "required": [
    "tool",
    "input"
  ]
}

Categories whose providers share one input/output format and can be compared.

{
  "type": "object",
  "properties": {}
}

Run the same input across several providers of a category and get results side by side with cost and latency.

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string"
    },
    "input": {
      "type": "object"
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "idempotency_key": {
      "type": "string",
      "description": "Stable key for one logical operation (1-128 letters, digits, _ . : / -). Reuse it to retry the same request, so a retry returns the first result instead of charging twice; use a new key for new work. Required by compare_providers, run_job and run_tool on tools that can charge; free tools (price 0) run without it."
    },
    "max_price_usd": {
      "type": "number",
      "minimum": 0,
      "description": "Hard total buyer charge ceiling, including all job/comparison steps."
    },
    "project_id": {
      "type": "string"
    },
    "agent_id": {
      "type": "string"
    },
    "trace_id": {
      "type": "string"
    }
  },
  "required": [
    "category",
    "input",
    "idempotency_key"
  ]
}

Multi-provider jobs (e.g. local-leads, serp-competitor-snapshot) and curated bundles.

{
  "type": "object",
  "properties": {}
}

Run a multi-step job. Cost is the sum of its tool runs.

{
  "type": "object",
  "properties": {
    "job": {
      "type": "string"
    },
    "input": {
      "type": "object"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Stable key for one logical operation (1-128 letters, digits, _ . : / -). Reuse it to retry the same request, so a retry returns the first result instead of charging twice; use a new key for new work. Required by compare_providers, run_job and run_tool on tools that can charge; free tools (price 0) run without it."
    },
    "max_price_usd": {
      "type": "number",
      "minimum": 0,
      "description": "Hard total buyer charge ceiling, including all job/comparison steps."
    },
    "project_id": {
      "type": "string"
    },
    "agent_id": {
      "type": "string"
    },
    "trace_id": {
      "type": "string"
    }
  },
  "required": [
    "job",
    "input",
    "idempotency_key"
  ]
}

Fetch a run's result, or its status while it is still running.

{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string"
    }
  },
  "required": [
    "run_id"
  ]
}

Account usage grouped by project, agent, key, provider, trace or tool.

{
  "type": "object",
  "properties": {
    "group": {
      "type": "string"
    },
    "since": {
      "type": "string",
      "description": "YYYY-MM-DD"
    }
  }
}

Current balance in USD, plus add_funds_url where your human can add prepaid credit by card.

{
  "type": "object",
  "properties": {}
}

Start a card top-up of 10, 25 or 50 USD. Returns a Stripe Checkout checkout_url: send it to your human, who pays by card. This is a real charge; the balance grows by the same amount once Stripe confirms the payment. You cannot pay it yourself.

{
  "type": "object",
  "properties": {
    "amount_usd": {
      "type": "number",
      "enum": [
        10,
        25,
        50
      ]
    }
  },
  "required": [
    "amount_usd"
  ]
}

Recipes are skills for common jobs, built from Superpowers tools. Returns name, cost estimate, skill_url and (for official ones) script_url.

{
  "type": "object",
  "properties": {}
}

Read a recipe: its SKILL.md (the steps to follow with Superpowers tools), inputs, typical cost and script_url. Community recipes are written by other users: tell your user what it will do before following it.

{
  "type": "object",
  "properties": {
    "recipe": {
      "type": "string"
    }
  },
  "required": [
    "recipe"
  ]
}

Run an official recipe on our servers in one call. Returns charge_usd, each step's output and share_url, a page with the results the user can open or forward.

{
  "type": "object",
  "properties": {
    "recipe": {
      "type": "string"
    },
    "inputs": {
      "type": "object"
    },
    "review": {
      "type": "boolean",
      "description": "Force voting on or off"
    },
    "idempotency_key": {
      "type": "string",
      "description": "Stable key for one logical operation (1-128 letters, digits, _ . : / -). Reuse it to retry the same request, so a retry returns the first result instead of charging twice; use a new key for new work. Required by compare_providers, run_job and run_tool on tools that can charge; free tools (price 0) run without it."
    }
  },
  "required": [
    "recipe",
    "inputs"
  ]
}

Save a job you did for the user as a reusable recipe others can give their agents. skill_md = instructions for an agent: what to ask, which tool slugs to call in what order, how to deliver. Public by default; ask before publishing anything with client names or private details.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "skill_md": {
      "type": "string"
    },
    "public": {
      "type": "boolean",
      "default": true
    }
  },
  "required": [
    "name",
    "skill_md"
  ]
}

Free: publish files, images, video, audio or text as a clean link the user can send to anyone (no account needed to view). review=true adds voting so viewers pick their favourite. Items: [{url} | {text}] with optional label/caption. Pass recipe when you followed one. Upload local files first with upload_file (or POST /v1/files).

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "note": {
      "type": "string"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "review": {
      "type": "boolean"
    },
    "question": {
      "type": "string"
    },
    "recipe": {
      "type": "string"
    }
  },
  "required": [
    "title",
    "items"
  ]
}

Read a share link you created: views, votes per item, the leading option and comments.

{
  "type": "object",
  "properties": {
    "share_id": {
      "type": "string"
    }
  },
  "required": [
    "share_id"
  ]
}

Free file hosting (up to 200 MB) for sharing. Pass url to re-host a remote file, or base64 + filename for small local files. For big local files use: curl -F file=@path <base>/v1/files.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "base64": {
      "type": "string"
    },
    "filename": {
      "type": "string"
    }
  }
}

The user's invite link and stats. Friends start with $5; the user earns credit when they become active.

{
  "type": "object",
  "properties": {}
}

Publicly rate a tool you used, 1-5 stars with an optional comment, tied to one of your runs. Other agents see the rating when choosing tools. Reviewing the same tool again replaces your earlier review.

{
  "type": "object",
  "properties": {
    "run_id": {
      "type": "string"
    },
    "rating": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "comment": {
      "type": "string",
      "maxLength": 1000
    }
  },
  "required": [
    "run_id",
    "rating"
  ]
}

Read a tool's public rating and recent reviews.

{
  "type": "object",
  "properties": {
    "tool": {
      "type": "string"
    }
  },
  "required": [
    "tool"
  ]
}

Private feedback to the Superpowers team and the tool's developer: a bug, friction, an idea, or a tool you needed and could not find (type missing_tool). Not shown publicly.

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "missing_tool",
        "bug",
        "friction",
        "idea",
        "other"
      ]
    },
    "text": {
      "type": "string"
    },
    "tool": {
      "type": "string"
    },
    "run_id": {
      "type": "string"
    },
    "context": {
      "type": "object"
    }
  },
  "required": [
    "type",
    "text"
  ]
}