Hermoso AI Discovery API

openapi: 3.2.0
info:
  title: Hermoso MCP server and OAuth (not the REST API) Discovery…
  version: 1.0.0
  summary: 'The Hermoso MCP endpoint and its OAuth documents. The REST API at /v1 is described by its own spec, generated from the router: https://app.hermoso.ai/openapi.json'
  description: 'Hermoso is an AI marketing studio built to be driven by an agent. The **public programmatic interface is a Model Context Protocol (MCP) server** at `POST https://app.hermoso.ai/mcp`, speaking JSON-RPC 2.0 over the MCP Streamable HTTP transport. One connection exposes the whole loop as tools: research the ads running in a market, generate on-brand image and video ads, publish or schedule them to the brand''s own channels, and build and read paid campaigns.


    **This document describes the MCP endpoint and the OAuth documents around it, and nothing else.** It is deliberately small, because the MCP surface genuinely is: the tools are not separate REST paths, they are `tools/call` methods on the single MCP endpoint. Call `tools/list` after `initialize` to enumerate them, or read the generated roster at .


    **There is also a public REST API, and it has its own document.** `/v1` covers publishing, scheduling, media, channels and credits on the same `hmk_` bearer token, and an agent with no account can provision one on a paid plan with `POST /v1/signup`. It is not described here, deliberately: its OpenAPI document is GENERATED from the same operations table the router is mounted from, so a second hand-written copy would be a second thing to go stale. Read it at (live, authoritative) or (static copy), and the prose at . `/v1` sends no CORS headers either, on purpose: an API key carries full account authority.


    **What genuinely has no contract are the routes under `/api` on the app.** They are shaped for our own web client, they authenticate with a browser session, and they change frequently. They are not documented anywhere because building against them will break. Use `/v1`, MCP or the npm CLI (`npm install -g hermoso`).


    ## Authenticating


    Two methods, both bearer tokens on the `Authorization` header:


    - **OAuth 2.1 authorization code + PKCE** — the path an MCP client takes. Dynamic client registration is open (RFC 7591), so a client can register itself with no pre-arranged credentials. Discovery follows RFC 9728 and RFC 8414: the `401` from `/mcp` carries a `WWW-Authenticate: Bearer resource_metadata="…"` header pointing at the protected-resource document.

    - **Agent key** — a long-lived `hmk_…` token minted at app.hermoso.ai → MCP & CLI → Terminal & API keys, for scripts and headless agents.


    `initialize` answers without a token so a client can discover the server before authenticating. `tools/call` requires one.


    ## Errors


    Every failure has the same JSON shape — `error` (a human-safe string), an optional `connector` key naming a provider that is not linked, and an optional `meta` object of machine-readable hints. The one rule worth memorising: **a 401 without a `connector` field means your key is bad; a 401 with one means that provider is not connected.** Branch on the field''s presence, never on the message text. Full contract: .


    ## Costs


    Generation is metered in credits with exact published per-render prices. Call the `hermoso_capabilities` tool — free and read-only — before rendering: it returns the valid model ids with their exact credit costs and what this workspace has connected. Machine-readable price list: .'
  termsOfService: https://hermoso.ai/terms/
  contact:
    name: Hermoso support
    email: admin@hermoso.ai
    url: https://hermoso.ai/contact/
  license:
    name: Proprietary
    url: https://hermoso.ai/terms/
servers:
- url: https://app.hermoso.ai
  description: Production
security:
- bearerAuth: []
- oauth2:
  - hermoso.research
  - hermoso.generate
tags:
- name: Discovery
  description: Machine-readable documents that let a client find and describe this server without being configured by hand.
paths:
  /.well-known/mcp.json:
    get:
      operationId: getMcpServerCard
      tags:
      - Discovery
      summary: Get the MCP server card
      description: 'The server''s own description in the Model Context Protocol server schema: its name, what it does, the remote Streamable HTTP URL, and the npm package that runs it over stdio. Generated live from the running server, so it is authoritative if it ever disagrees with the prose on the website.'
      security:
      - {}
      responses:
        '200':
          description: The server card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerCard'
  /.well-known/oauth-protected-resource:
    get:
      operationId: getProtectedResourceMetadata
      tags:
      - Discovery
      summary: Get OAuth protected-resource metadata (RFC 9728)
      description: Names the resource an access token must be audience-bound to, the authorization servers that may issue one, and the scopes this resource understands. An unauthenticated request to `/mcp` points here from its `WWW-Authenticate` header, which is how a client bootstraps the whole flow knowing only the MCP URL.
      security:
      - {}
      responses:
        '200':
          description: Protected-resource metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtectedResourceMetadata'
  /.well-known/oauth-authorization-server:
    get:
      operationId: getAuthorizationServerMetadata
      tags:
      - Discovery
      summary: Get OAuth authorization server metadata (RFC 8414)
      description: The authorization, token and dynamic-registration endpoints, the grant and response types supported, the PKCE methods accepted, and the scopes on offer. Everything a client needs to run the flow without being configured by hand.
      security:
      - {}
      responses:
        '200':
          description: Authorization server metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationServerMetadata'
components:
  schemas:
    McpServerCard:
      type: object
      title: McpServerCard
      description: The Model Context Protocol server description, as published in the MCP registry.
      required:
      - name
      - description
      - version
      properties:
        $schema:
          type: string
          format: uri
          description: The MCP server schema this document conforms to.
        name:
          type: string
          description: The registry name of the server.
          examples:
          - io.github.hermoso-ai/hermoso
        title:
          type: string
          description: The display name.
        description:
          type: string
          description: What the server does, written for an agent deciding whether to reach for it.
        version:
          type: string
          description: The published version, matching the npm package.
        websiteUrl:
          type: string
          format: uri
          description: The documentation home.
        repository:
          type: object
          description: Where the source lives.
          properties:
            url:
              type: string
              format: uri
              description: The repository URL.
            source:
              type: string
              description: The hosting service.
              examples:
              - github
            subfolder:
              type: string
              description: The path within the repository.
        remotes:
          type: array
          description: Hosted transports a client can connect to directly.
          items:
            type: object
            required:
            - type
            - url
            properties:
              type:
                type: string
                description: The transport.
                examples:
                - streamable-http
              url:
                type: string
                format: uri
                description: The endpoint URL.
        packages:
          type: array
          description: Packages that run the same server locally over stdio.
          items:
            type: object
            additionalProperties: true
    ProtectedResourceMetadata:
      type: object
      title: ProtectedResourceMetadata
      description: RFC 9728 protected-resource metadata.
      required:
      - resource
      - authorization_servers
      properties:
        resource:
          type: string
          format: uri
          description: The resource identifier an access token must be bound to.
          examples:
          - https://app.hermoso.ai/mcp
        authorization_servers:
          type: array
          description: Issuers permitted to mint tokens for this resource.
          items:
            type: string
            format: uri
        scopes_supported:
          type: array
          description: The scopes this resource understands.
          items:
            type: string
            enum:
            - hermoso.research
            - hermoso.generate
        bearer_methods_supported:
          type: array
          description: How a token may be presented.
          items:
            type: string
            enum:
            - header
    AuthorizationServerMetadata:
      type: object
      title: AuthorizationServerMetadata
      description: RFC 8414 authorization server metadata.
      required:
      - issuer
      - authorization_endpoint
      - token_endpoint
      properties:
        issuer:
          type: string
          format: uri
          description: The issuer identifier.
        authorization_endpoint:
          type: string
          format: uri
          description: Where a browser starts the flow.
        token_endpoint:
          type: string
          format: uri
          description: Where a code is exchanged for a token.
        registration_endpoint:
          type: string
          format: uri
          description: Where a client registers itself (RFC 7591).
        response_types_supported:
          type: array
          description: Supported response types.
          items:
            type: string
            enum:
            - code
        grant_types_supported:
          type: array
          description: Supported grant types.
          items:
            type: string
            enum:
            - authorization_code
        code_challenge_methods_supported:
          type: array
          description: Supported PKCE methods. `plain` is deliberately not offered.
          items:
            type: string
            enum:
            - S256
        token_endpoint_auth_methods_supported:
          type: array
          description: Clients are public, so no secret is issued and none is accepted.
          items:
            type: string
            enum:
            - none
        scopes_supported:
          type: array
          description: The scopes on offer.
          items:
            type: string
            enum:
            - hermoso.research
            - hermoso.generate
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A Hermoso agent key (`hmk_…`), minted at app.hermoso.ai → MCP & CLI → Terminal & API keys. Sent as `Authorization: Bearer hmk_…`. A key is pinned to one brand workspace, and that pin is re-authorised on the server for every request — it is never read off a header the caller controls.'
    oauth2:
      type: oauth2
      description: OAuth 2.1 authorization code flow with PKCE (S256). Dynamic client registration is open, so no credentials need to be arranged in advance.
      flows:
        authorizationCode:
          authorizationUrl: https://app.hermoso.ai/oauth/authorize
          tokenUrl: https://app.hermoso.ai/oauth/token
          scopes:
            hermoso.research: 'Names the research surface: the Meta, Google and LinkedIn ad libraries, organic social search, competitor teardowns, and reads of the brand, workspace, credit balance and job status.'
            hermoso.generate: 'Names the acting surface: generating creative, publishing to connected channels, and building and reading ad campaigns. Renders consume credits, and any call that arms real ad spend requires an explicit per-call confirmation regardless of the token presented.'
externalDocs:
  description: Hermoso developer documentation
  url: https://hermoso.ai/docs/