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

    their first US$1 online. There is no hosted execution or payment API: the

    paid continuation happens inside the user''s own Hermes Agent through the

    installable skill. This document describes every public machine-readable

    resource on hermesstartup.com so agents can discover and consume the site

    without JavaScript or guessing.


    Authentication: none. All endpoints are unauthenticated GET requests.


    Error responses: any unknown /api/* path returns the JSON object described

    by components/schemas/Error with HTTP status 404 (see /api-error.json).

    Unknown non-API paths return the standard HTML 404 page. Agents should

    parse the JSON error shape on API paths and the HTML page elsewhere.


    Rate limiting: static pages are not rate-limited and need no throttling.

    The telemetry API on api.hermesstartup.com is rate-limited and returns the

    RFC 9218 RateLimit-* headers (RateLimit-Limit, RateLimit-Remaining,

    RateLimit-Reset) plus Retry-After on HTTP 429; agents calling it should

    self-throttle from those headers and honor Retry-After.


    Markdown negotiation: every HTML page advertises its agent-facing markdown

    mirror with a <link rel="alternate" type="text/markdown"> element; the

    homepage points to /for-agents.md. Responses that serve markdown or JSON

    include "Vary: Accept, Accept-Encoding" so caches never serve the wrong

    variant to a client that asked for another one.

    '
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'