{
  "openapi": "3.1.0",
  "info": {
    "title": "Hermes Startup public resources",
    "version": "0.2.0",
    "summary": "Read-only public documents served by hermesstartup.com for AI agents and developers.",
    "description": "Hermes Startup is a private Hermes Agent workflow that helps a user make\ntheir first US$1 online. There is no hosted execution or payment API: the\npaid continuation happens inside the user's own Hermes Agent through the\ninstallable skill. This document describes every public machine-readable\nresource on hermesstartup.com so agents can discover and consume the site\nwithout JavaScript or guessing.\n\nAuthentication: none. All endpoints are unauthenticated GET requests.\n\nError responses: any unknown /api/* path returns the JSON object described\nby components/schemas/Error with HTTP status 404 (see /api-error.json).\nUnknown non-API paths return the standard HTML 404 page. Agents should\nparse the JSON error shape on API paths and the HTML page elsewhere.\n\nRate limiting: static pages are not rate-limited and need no throttling.\nThe telemetry API on api.hermesstartup.com is rate-limited and returns the\nRFC 9218 RateLimit-* headers (RateLimit-Limit, RateLimit-Remaining,\nRateLimit-Reset) plus Retry-After on HTTP 429; agents calling it should\nself-throttle from those headers and honor Retry-After.\n\nMarkdown negotiation: every HTML page advertises its agent-facing markdown\nmirror with a <link rel=\"alternate\" type=\"text/markdown\"> element; the\nhomepage points to /for-agents.md. Responses that serve markdown or JSON\ninclude \"Vary: Accept, Accept-Encoding\" so caches never serve the wrong\nvariant to a client that asked for another one.\n"
  },
  "servers": [
    {
      "url": "https://hermesstartup.com"
    }
  ],
  "tags": [
    {
      "name": "pages",
      "description": "Human-readable HTML pages (server-rendered, readable without JavaScript)."
    },
    {
      "name": "agent-resources",
      "description": "Machine-readable documents for AI agents."
    },
    {
      "name": "developer-resources",
      "description": "API descriptions, error contract, and discovery files for developers."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getHermesStartupHomepage",
        "summary": "Fetch the Hermes Startup homepage",
        "description": "Server-rendered HTML with the full product description, one H1, structured data, and the activation prompt. The text is readable in raw HTML with JavaScript disabled.",
        "tags": [
          "pages"
        ],
        "responses": {
          "200": {
            "description": "Homepage HTML document.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string",
                  "description": "Complete HTML document."
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/about": {
      "get": {
        "operationId": "getHermesStartupAbout",
        "summary": "Fetch the About page",
        "description": "Who Hermes Startup is for, how it works, who provides it, and its boundaries.",
        "tags": [
          "pages"
        ],
        "responses": {
          "200": {
            "description": "About page HTML document.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/contact": {
      "get": {
        "operationId": "getHermesStartupContact",
        "summary": "Fetch the Contact page",
        "description": "Support and privacy contact channels (email and X) with guidance on what to include.",
        "tags": [
          "pages"
        ],
        "responses": {
          "200": {
            "description": "Contact page HTML document.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/developers": {
      "get": {
        "operationId": "getHermesStartupDevelopers",
        "summary": "Fetch the developer portal",
        "description": "Quickstart, resource index, API conventions (auth, JSON errors, rate limits, markdown mirrors), and sandbox path for developers and agents.",
        "tags": [
          "pages",
          "developer-resources"
        ],
        "responses": {
          "200": {
            "description": "Developer portal HTML document.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getHermesStartupAgentGuide",
        "summary": "Read the canonical product guide for AI agents",
        "description": "The llms.txt agent index: what Hermes Startup is, when to use it, how to call it, and its safety boundaries.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "Plain-text agent guide.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Markdown-formatted text."
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "operationId": "getHermesStartupFullAgentContext",
        "summary": "Read the expanded agent context",
        "description": "The full llms.txt-style reference with capabilities, evidence-first sequence, availability, and canonical resources.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "Plain-text full agent context.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/index.json": {
      "get": {
        "operationId": "getHermesStartupAgentIndex",
        "summary": "Read the structured agent index",
        "description": "JSON version of the canonical handoff with positioning, primary action, free and paid paths, capabilities, safety, availability, and resources.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "Structured agent index.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "name",
                    "canonical_url",
                    "primary_action"
                  ],
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "canonical_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "primary_action": {
                      "type": "object",
                      "required": [
                        "install_command",
                        "start_command"
                      ],
                      "properties": {
                        "install_command": {
                          "type": "string"
                        },
                        "start_command": {
                          "type": "string"
                        }
                      }
                    },
                    "safety": {
                      "type": "object"
                    },
                    "resources": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/for-agents.md": {
      "get": {
        "operationId": "getHermesStartupAgentHandoff",
        "summary": "Read the agent handoff guide",
        "description": "Exact next steps and safety boundaries for an AI agent whose user shares hermesstartup.com, plus the markdown mirror of the homepage.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "Markdown handoff guide.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/website-to-api.md": {
      "get": {
        "operationId": "getHermesStartupWebsiteToApi",
        "summary": "Read the website-to-API service description",
        "description": "How Hermes Startup turns any website's hidden JSON calls into a private static API client for the user's agent.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "Markdown service description.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/skill/SKILL.md": {
      "get": {
        "operationId": "getHermesStartupSkill",
        "summary": "Read the installable Hermes Startup skill",
        "description": "The portable Hermes Agent skill. Install with \"hermes skills install https://hermesstartup.com/skill/SKILL.md\" then start with /startup.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "Hermes skill document.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/openapi.yaml": {
      "get": {
        "operationId": "getHermesStartupOpenapiYaml",
        "summary": "Read this OpenAPI description as YAML",
        "description": "The canonical machine-readable description of all public resources.",
        "tags": [
          "developer-resources"
        ],
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document in YAML.",
            "content": {
              "text/yaml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getHermesStartupOpenapiJson",
        "summary": "Read this OpenAPI description as JSON",
        "description": "JSON mirror of /openapi.yaml for tooling that only consumes JSON.",
        "tags": [
          "developer-resources"
        ],
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document in JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/api-error.json": {
      "get": {
        "operationId": "getHermesStartupApiErrorExample",
        "summary": "Read the JSON error contract example",
        "description": "The exact JSON body returned with HTTP 404 for unknown /api/* paths.",
        "tags": [
          "developer-resources"
        ],
        "responses": {
          "200": {
            "description": "Example JSON error object.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "getHermesStartupSitemap",
        "summary": "Read the XML sitemap",
        "description": "All indexable public URLs with lastmod dates. HTML pages are listed at their canonical extensionless URLs.",
        "tags": [
          "developer-resources"
        ],
        "responses": {
          "200": {
            "description": "XML sitemap document.",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/robots.txt": {
      "get": {
        "operationId": "getHermesStartupRobots",
        "summary": "Read robots.txt",
        "description": "Allowlist for known AI crawler user agents plus the sitemap pointer.",
        "tags": [
          "developer-resources"
        ],
        "responses": {
          "200": {
            "description": "robots.txt document.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/.well-known/ai-plugin.json": {
      "get": {
        "operationId": "getHermesStartupAiPluginManifest",
        "summary": "Read the AI plugin manifest",
        "description": "OpenAI-style plugin manifest describing the installable skill and its OpenAPI reference.",
        "tags": [
          "developer-resources"
        ],
        "responses": {
          "200": {
            "description": "Plugin manifest.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/.well-known/security.txt": {
      "get": {
        "operationId": "getHermesStartupSecurityTxt",
        "summary": "Read the security contact file",
        "description": "Security disclosure contact per RFC 9116.",
        "tags": [
          "developer-resources"
        ],
        "responses": {
          "200": {
            "description": "security.txt document.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/.well-known/ucp": {
      "get": {
        "operationId": "getHermesStartupUcpProfile",
        "summary": "Read the UCP business profile",
        "description": "Universal Commerce Protocol (ucp.dev) business profile declaring the Hermes Startup REST service and its prepaid-wallet payment handler, for agent-driven discovery and payment.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "UCP business profile document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/.well-known/api-catalog": {
      "get": {
        "operationId": "getHermesStartupApiCatalog",
        "summary": "Read the RFC 9727 API catalog",
        "description": "Linkset (application/linkset+json) advertising the OpenAPI service description and developer documentation, per RFC 9727.",
        "tags": [
          "developer-resources"
        ],
        "responses": {
          "200": {
            "description": "application/linkset+json document.",
            "content": {
              "application/linkset+json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/.well-known/agent-skills/index.json": {
      "get": {
        "operationId": "getHermesStartupAgentSkillsIndex",
        "summary": "Read the Agent Skills discovery index",
        "description": "Agent Skills Discovery RFC v0.2.0 index of the installable Hermes Startup skill with its sha256 digest.",
        "tags": [
          "developer-resources"
        ],
        "responses": {
          "200": {
            "description": "application/json document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/.well-known/ai-catalog.json": {
      "get": {
        "operationId": "getHermesStartupAiCatalog",
        "summary": "Read the ARD AI Catalog manifest",
        "description": "Agentic Resource Discovery AI Catalog (specVersion 1.0) listing the OpenAPI description, skill, agent guide, structured index, and developer portal with representative queries.",
        "tags": [
          "developer-resources"
        ],
        "responses": {
          "200": {
            "description": "application/json document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/auth.md": {
      "get": {
        "operationId": "getHermesStartupAuth",
        "summary": "Read the auth.md agent registration statement",
        "description": "Authentication and credentials statement for agents: no API key or registration is required for public resources.",
        "tags": [
          "developer-resources"
        ],
        "responses": {
          "200": {
            "description": "text/markdown document.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/about.md": {
      "get": {
        "operationId": "getHermesStartupAboutMarkdown",
        "summary": "Read the about page as markdown",
        "description": "Markdown mirror of the about page for agents that request Accept: text/markdown; also served directly at this URL.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "text/markdown document.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/contact.md": {
      "get": {
        "operationId": "getHermesStartupContactMarkdown",
        "summary": "Read the contact page as markdown",
        "description": "Markdown mirror of the contact page for agents that request Accept: text/markdown; also served directly at this URL.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "text/markdown document.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/developers.md": {
      "get": {
        "operationId": "getHermesStartupDevelopersMarkdown",
        "summary": "Read the developers page as markdown",
        "description": "Markdown mirror of the developers page for agents that request Accept: text/markdown; also served directly at this URL.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "text/markdown document.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/privacy.md": {
      "get": {
        "operationId": "getHermesStartupPrivacyMarkdown",
        "summary": "Read the privacy page as markdown",
        "description": "Markdown mirror of the privacy page for agents that request Accept: text/markdown; also served directly at this URL.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "text/markdown document.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/terms.md": {
      "get": {
        "operationId": "getHermesStartupTermsMarkdown",
        "summary": "Read the terms page as markdown",
        "description": "Markdown mirror of the terms page for agents that request Accept: text/markdown; also served directly at this URL.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "text/markdown document.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    },
    "/changelog.md": {
      "get": {
        "operationId": "getHermesStartupChangelogMarkdown",
        "summary": "Read the changelog page as markdown",
        "description": "Markdown mirror of the changelog page for agents that request Accept: text/markdown; also served directly at this URL.",
        "tags": [
          "agent-resources"
        ],
        "responses": {
          "200": {
            "description": "text/markdown document.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/JsonError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Machine-readable JSON error body returned for unknown /api/* paths (HTTP 404).",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code (for example \"not_found\")."
              },
              "message": {
                "type": "string",
                "description": "Human-readable summary of the error."
              },
              "resolution": {
                "type": "string",
                "description": "What an agent should do next to resolve the error."
              },
              "docs": {
                "type": "string",
                "format": "uri",
                "description": "URL of the developer portal with the full conventions."
              }
            }
          }
        }
      }
    },
    "responses": {
      "JsonError": {
        "description": "JSON error response for unknown API paths.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}