{"object":"api","version":"2026-08-26","documentation":"https://hermoso.ai/docs/api","openapi":"https://app.hermoso.ai/openapi.json","compatibility":"ADD FREELY, NEVER BREAK. Inside `/v1` we add endpoints, optional request fields and response fields without notice, and enums grow — a new publishing channel is an addition, not a version. We never remove a field, change its type or meaning, change a default, or change the status code of an existing condition. Anything that cannot obey that gets a `/v2`, and `/v1` then keeps serving for at least 12 months carrying `Deprecation` and `Sunset` headers (RFC 8594).\n\nSo: **ignore fields you do not recognise, and tolerate enum values you have not seen.** Those two habits are what make the promise worth anything.\n\nThe `/api/*` routes this app uses internally are NOT part of any contract. They change without notice and are not documented here. Do not call them. **One exception, and it is listed in `paths` below:** `POST /api/billing/machine-payment`. The Machine Payments Protocol discovers a payable endpoint by reading `x-payment-info` out of an OpenAPI document, so an endpoint that is not in this document cannot be found by a wallet at all. It is not in `/v1` because a `402` challenge has to be a raw response carrying `WWW-Authenticate`, and every `/v1` handler returns an object this API wraps in its own envelope. Treat that one path as covered by the same never-break promise as `/v1`.","passthrough":"`/v1/tools` is FULL PARITY with the Hermoso toolset, and it EVOLVES WITH IT. Two different promises live in this API, and it is worth knowing which one you are standing on.\n\n**The modelled resources** — `/v1/posts`, `/v1/channels`, `/v1/media`, `/v1/credits` — obey the compatibility promise above in full. Add freely, never break. Build a product on them.\n\n**The tool passthrough** — `/v1/tools` and `/v1/tools/{name}` — reaches everything else Hermoso does: research, generation, publishing, paid campaigns on every connected ad platform, analytics, files, workspace. Its ENVELOPE is stable under the same promise: the routes, the authentication, the error shape, the rate-limit headers, the idempotency semantics and this document. THE TOOLS INSIDE IT ARE NOT FROZEN — their arguments and results improve as the tools do, continuously and without a version bump.\n\nSo read the roster rather than pinning it: `GET /v1/tools` is a live read, filterable by area and searchable, and `GET /v1/tools/{name}` is the current schema for one tool. Neither tier is the lesser door — pick per job.","tools":{"url":"https://app.hermoso.ai/v1/tools","method":"GET","note":"The live roster of everything callable over HTTP, grouped by area and searchable. Read it rather than hard-coding it."},"authentication":"Authorization: Bearer hmk_... — create a key in the app under Settings, Agents & API, or run the OAuth authorization-code flow (which mints the same kind of key).","signup":{"url":"https://app.hermoso.ai/v1/signup","method":"POST","requires":"a paid plan","note":"Agentic signup provisions an account only against a completed payment — no free plan on this path. A person signing up at https://app.hermoso.ai still gets the free plan."},"browser_support":false,"rate_limits":{"read_per_minute":300,"write_per_minute":60,"scope":"per API key"},"resources":["channels","posts","media","credits","tools","signup"]}