{
  "openapi": "3.1.0",
  "info": {
    "title": "Codex Stellarum Public Surface",
    "version": "1.0.0",
    "summary": "Machine-readable description of the publicly available routes and resources on codexstellarum.com.",
    "description": "Codex Stellarum is a fine art print studio that turns GitHub contribution history into vintage astronomical star atlases. This specification describes the public, unauthenticated GET endpoints that crawlers, AI agents, and integrators may use to discover content. Checkout, fulfilment, and rendering endpoints are intentionally omitted: they are private, webhook-driven, or auth-gated and are not part of the public surface.",
    "contact": {
      "name": "Codex Stellarum",
      "url": "https://codexstellarum.com/about"
    },
    "license": {
      "name": "All rights reserved",
      "url": "https://codexstellarum.com/terms"
    },
    "termsOfService": "https://codexstellarum.com/terms"
  },
  "servers": [
    { "url": "https://codexstellarum.com", "description": "Production" }
  ],
  "tags": [
    { "name": "Discovery", "description": "Well-known files for crawlers and agents." },
    { "name": "Pages", "description": "Public HTML pages." },
    { "name": "Atlas", "description": "Dynamic preview pages for a GitHub subject." },
    { "name": "Editorial", "description": "Long-form essays and journal entries." }
  ],
  "paths": {
    "/sitemap.xml": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Sitemap of indexable pages",
        "description": "Standard XML sitemap listing every public route, including all blog entries.",
        "responses": {
          "200": {
            "description": "Sitemap document.",
            "content": { "application/xml": {} }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": ["Discovery"],
        "summary": "AI crawler guide",
        "description": "Plain-text index following the llms.txt convention, summarising the site and linking to its principal pages.",
        "responses": {
          "200": { "description": "Plain text guide.", "content": { "text/plain": {} } }
        }
      }
    },
    "/robots.txt": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Crawler directives",
        "responses": {
          "200": { "description": "Plain text directives.", "content": { "text/plain": {} } }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "This specification",
        "responses": {
          "200": { "description": "OpenAPI document.", "content": { "application/json": {} } }
        }
      }
    },
    "/": {
      "get": {
        "tags": ["Pages"],
        "summary": "Landing page",
        "description": "Marketing landing with search for any GitHub username, repository, or organisation.",
        "responses": { "200": { "description": "HTML document.", "content": { "text/html": {} } } }
      }
    },
    "/about": {
      "get": { "tags": ["Pages"], "summary": "About the studio", "responses": { "200": { "description": "HTML document.", "content": { "text/html": {} } } } }
    },
    "/business": {
      "get": { "tags": ["Pages"], "summary": "Commissions for teams and organisations", "responses": { "200": { "description": "HTML document.", "content": { "text/html": {} } } } }
    },
    "/guestbook": {
      "get": { "tags": ["Pages"], "summary": "Testimonials from recipients", "responses": { "200": { "description": "HTML document.", "content": { "text/html": {} } } } }
    },
    "/affiliates": {
      "get": { "tags": ["Pages"], "summary": "Partner programme", "responses": { "200": { "description": "HTML document.", "content": { "text/html": {} } } } }
    },
    "/refund-challenge": {
      "get": { "tags": ["Pages"], "summary": "Refund policy", "responses": { "200": { "description": "HTML document.", "content": { "text/html": {} } } } }
    },
    "/privacy": {
      "get": { "tags": ["Pages"], "summary": "Privacy policy", "responses": { "200": { "description": "HTML document.", "content": { "text/html": {} } } } }
    },
    "/terms": {
      "get": { "tags": ["Pages"], "summary": "Terms of service", "responses": { "200": { "description": "HTML document.", "content": { "text/html": {} } } } }
    },
    "/refunds": {
      "get": { "tags": ["Pages"], "summary": "Cancellation and refund policy", "responses": { "200": { "description": "HTML document.", "content": { "text/html": {} } } } }
    },
    "/blog": {
      "get": { "tags": ["Editorial"], "summary": "Journal index", "responses": { "200": { "description": "HTML document.", "content": { "text/html": {} } } } }
    },
    "/blog/{slug}": {
      "get": {
        "tags": ["Editorial"],
        "summary": "A single journal entry",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "URL-safe slug of the article. See /sitemap.xml for the full list.",
            "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" },
            "example": "the-rosette-layout"
          }
        ],
        "responses": {
          "200": { "description": "HTML document.", "content": { "text/html": {} } },
          "404": { "description": "No article with that slug." }
        }
      }
    },
    "/chart/{username}": {
      "get": {
        "tags": ["Atlas"],
        "summary": "Atlas preview for a GitHub user",
        "description": "Renders a live preview of the star atlas generated from the named GitHub profile, with configurable theme, layout, date range, and print size.",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "description": "Any public GitHub username.",
            "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,39}$" },
            "example": "octocat"
          }
        ],
        "responses": {
          "200": { "description": "HTML document.", "content": { "text/html": {} } }
        }
      }
    },
    "/repo/{owner}/{repo}": {
      "get": {
        "tags": ["Atlas"],
        "summary": "Atlas preview for a GitHub repository",
        "parameters": [
          { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" }, "example": "vercel" },
          { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" }, "example": "next.js" }
        ],
        "responses": { "200": { "description": "HTML document.", "content": { "text/html": {} } } }
      }
    },
    "/org/{orgname}": {
      "get": {
        "tags": ["Atlas"],
        "summary": "Organisation redirect",
        "description": "Resolves a GitHub organisation to its top repositories and points visitors at repository-specific prints.",
        "parameters": [
          { "name": "orgname", "in": "path", "required": true, "schema": { "type": "string" }, "example": "github" }
        ],
        "responses": { "200": { "description": "HTML document.", "content": { "text/html": {} } } }
      }
    }
  }
}