# Hermoso: A Marketing API for Builders: Tool Search, Prices, Warnings

> Machine-readable twin of https://hermoso.ai/blog/marketing-api-for-builders/. Generated from the shipped page. Do not edit by hand.
> Full agent guide: https://hermoso.ai/llms.txt · MCP: https://app.hermoso.ai/mcp

[Blog](https://hermoso.ai/blog/)

# A marketing API for builders: ranked tool search with prices, every tool in one list, and warnings

The Hermoso REST API now ranks tool search the way agents do, shows each tool's price, lists every tool with include=all and warns about any parameter it ignored. Quick start inside.

By the Hermoso team · Launched November 17, 2026 · Updated November 17, 2026 · 4 min read

Hermoso has a plain REST API at `app.hermoso.ai/v1` with the same tools your AI agent uses: research ads, make image and video ads, post to social accounts and run campaigns. We gave a fresh agent nothing but the docs and asked it to build on the API. Everywhere it stumbled, we fixed the API. Here is what changed.

## Tool search that finds the tool

`GET /v1/tools?search=email outreach` used to return nothing while agents found the email tools in one try. Search now uses the same ranking agents use, says how many tools match strongly, and every row carries the tool's price, so you know what a call costs before you make it.

## Every tool, even the ones you cannot call yet

`include=all` lists every tool. The ones your workspace cannot call yet are marked unavailable, with the reason, the connection they need and a link that connects it for that brand. The default list is unchanged, field for field.

## Warnings instead of silence

Every operation now returns a `warnings` list naming any query parameter or body field it does not take, with a suggestion when it looks like a slip (`query` for `search`, `text` for `caption`). The request still runs; you just find out.

## Smaller fixes

- `GET /v1/models?sort=credits` sorts the models by price.

- `/v1/media` takes a JSON body with a `url` and hosts that file.

- A tool the server holds back answers "tool unavailable" instead of a confusing sign-in error.

## A worked example

A developer building a Shopify app wants each merchant's new product turned into an Instagram post. With a key from the app, she calls `GET /v1/tools?search=post to instagram`, sees the posting tool and its price at the top, and calls it. A typo in her first request (`captoin`) comes back with a warning and a suggestion instead of a post with no caption. When a merchant has not connected Instagram, `include=all` gives her the connect link to show them.

## Start here

The [API docs](https://hermoso.ai/docs/api/) now open with a quick start: make a key in [the app](https://app.hermoso.ai/?src=blog-marketing-api-for-builders&tab=api-keys), make a first call, run a generation and send a connect link. Prefer MCP? The same tools are at [app.hermoso.ai/mcp](https://hermoso.ai/mcp/).

## Questions people ask

### Does Hermoso have a REST API?

Yes, at app.hermoso.ai/v1, with the same tools agents use over MCP. You call it with an API key from the app.

### How do I find the right tool over the API?

Call GET /v1/tools with search and a few words of the task. Results are ranked and each one carries its price.

### Can I see tools that need a connection I have not made?

Yes. Add include=all and those tools are listed as unavailable, with the connection they need and a link that connects it.

### What happens if I send a parameter the API does not take?

The request runs and the response carries a warnings list naming the parameter, with a suggestion if it looks like a typo.
