{
  "openapi": "3.1.0",
  "info": {
    "title": "Golden Analytics website API",
    "version": "1.0.0",
    "summary": "Public HTTP surface of goldenanalytics.com.",
    "description": "The public endpoints of the Golden Analytics marketing site.\n\nEvery page URL also answers `Accept: text/markdown` with a markdown\nrendition of the same content (see acceptmarkdown.com); responses carry\n`Vary: Accept`.\n\nErrors are always JSON with a stable `code`, a `message` and a `hint`.\n\nScope vocabulary: https://goldenanalytics.com/.well-known/oauth-protected-resource\n\nFor agents: an MCP server exposing this content as tools lives at\n`POST https://goldenanalytics.com/mcp` (Streamable HTTP, no credential). When to use\nit and which endpoint answers what: https://goldenanalytics.com/agents.md. Human-readable\nindex of everything here: https://goldenanalytics.com/developers.",
    "contact": {
      "name": "Golden Analytics",
      "url": "https://goldenanalytics.com/about/contact"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://goldenanalytics.com/terms-of-use"
    }
  },
  "servers": [
    {
      "url": "https://goldenanalytics.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "llms.txt",
    "url": "https://goldenanalytics.com/llms.txt"
  },
  "x-scopes": {
    "content:read": "Read published site content (pages, posts, markdown views).",
    "search:read": "Query the site search index.",
    "forms:read": "Read a public form definition so it can be rendered.",
    "contact:write": "Submit the public contact form.",
    "waitlist:write": "Submit a sign-up / wait-list entry.",
    "cache:revalidate": "Invalidate the rendered-page cache. Sanity webhook only.",
    "draft:preview": "Enter draft-preview mode. Sanity Studio editors only."
  },
  "tags": [
    {
      "name": "content",
      "description": "Published site content."
    },
    {
      "name": "forms",
      "description": "Public form definitions and submissions."
    },
    {
      "name": "internal",
      "description": "Authenticated endpoints for the CMS."
    },
    {
      "name": "agents",
      "description": "Endpoints published for AI agents."
    }
  ],
  "paths": {
    "/api/search": {
      "get": {
        "tags": [
          "content"
        ],
        "operationId": "searchContent",
        "summary": "Full-text search across published site content.",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "search:read"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search term. An empty term returns an empty array.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching documents, most relevant first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SearchResult"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Search backend unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "tags": [
          "forms"
        ],
        "operationId": "submitContactForm",
        "summary": "Submit the public contact form.",
        "description": "Routed to an inbox by `intentValue`. Requests that trip the anti-spam heuristics receive `200 {\"ok\":true}` without being delivered.",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "contact:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactSubmission"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Mail transport not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Mail transport rejected the message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/check-email": {
      "post": {
        "tags": [
          "forms"
        ],
        "operationId": "checkEmail",
        "summary": "Check whether an email is already on the wait list or blocked.",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "waitlist:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "portalId": {
                    "type": "string"
                  },
                  "formId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Check result. Fails open: on any internal error the response is `{exists:false,blocked:false}`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "exists",
                    "blocked"
                  ],
                  "properties": {
                    "exists": {
                      "type": "boolean"
                    },
                    "blocked": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/sheets": {
      "post": {
        "tags": [
          "forms"
        ],
        "operationId": "appendWaitlistRow",
        "summary": "Append a sign-up submission to the wait-list spreadsheet.",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "waitlist:write"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "fields"
                ],
                "properties": {
                  "fields": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "label",
                        "value"
                      ],
                      "properties": {
                        "label": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "value": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Row appended, or skipped as a duplicate.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "duplicate": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Spreadsheet backend not configured or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/hubspot-form": {
      "get": {
        "tags": [
          "forms"
        ],
        "operationId": "getFormDefinition",
        "summary": "Fetch a public form definition by id.",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "forms:read"
        ],
        "parameters": [
          {
            "name": "formId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Form definition (field groups, labels, validation).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "`formId` missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Form backend not configured or unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/revalidate": {
      "post": {
        "tags": [
          "internal"
        ],
        "operationId": "revalidateCache",
        "summary": "Invalidate the rendered-page cache (CMS webhook).",
        "description": "Requires a valid HMAC signature over the raw body, generated with the shared webhook secret.",
        "security": [
          {
            "sanityWebhookSignature": []
          }
        ],
        "x-required-scopes": [
          "cache:revalidate"
        ],
        "responses": {
          "200": {
            "description": "Cache invalidated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revalidated": {
                      "type": "boolean"
                    },
                    "now": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid signature.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Webhook secret not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/draft-mode/enable": {
      "get": {
        "tags": [
          "internal"
        ],
        "operationId": "enableDraftMode",
        "summary": "Enter draft-preview mode (CMS editors).",
        "security": [
          {
            "sanityPreviewSecret": []
          }
        ],
        "x-required-scopes": [
          "draft:preview"
        ],
        "responses": {
          "307": {
            "description": "Draft mode enabled; redirect into the site."
          },
          "401": {
            "description": "Invalid preview secret.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Preview not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/draft-mode/disable": {
      "get": {
        "tags": [
          "internal"
        ],
        "operationId": "disableDraftMode",
        "summary": "Leave draft-preview mode.",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "draft:preview"
        ],
        "responses": {
          "307": {
            "description": "Draft mode disabled."
          }
        }
      }
    },
    "/{path}": {
      "get": {
        "tags": [
          "content"
        ],
        "operationId": "getPage",
        "summary": "Fetch any page as HTML or Markdown.",
        "description": "Content negotiation per acceptmarkdown.com. `Accept: text/markdown` returns `text/markdown; charset=utf-8`; anything else returns the HTML page. All responses carry `Vary: Accept, Accept-Encoding`.",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "content:read"
        ],
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "description": "Any site path, e.g. `pricing` or `blog/some-post`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "text/html",
                "text/markdown"
              ],
              "default": "text/html"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page.",
            "headers": {
              "Vary": {
                "schema": {
                  "type": "string"
                },
                "description": "Always includes `Accept`."
              }
            },
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such page. Markdown clients get a recovery body linking the sitemap, llms.txt and section indexes.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "406": {
            "description": "None of the requested media types can be produced.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "tags": [
          "content"
        ],
        "operationId": "getSitemap",
        "summary": "Every indexable URL, generated from the CMS.",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "content:read"
        ],
        "responses": {
          "200": {
            "description": "urlset",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": [
          "content"
        ],
        "operationId": "getLlmsTxt",
        "summary": "Condensed site guide for language models.",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "content:read"
        ],
        "responses": {
          "200": {
            "description": "Plain text",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "tags": [
          "content"
        ],
        "operationId": "getLlmsFullTxt",
        "summary": "Long-form site guide for language models.",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "content:read"
        ],
        "responses": {
          "200": {
            "description": "Plain text",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agents.md": {
      "get": {
        "tags": [
          "agents"
        ],
        "operationId": "getAgentInstructions",
        "summary": "When to use this site, which endpoint answers what, and the conventions it follows.",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "content:read"
        ],
        "responses": {
          "200": {
            "description": "Markdown instructions.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/pricing.md": {
      "get": {
        "tags": [
          "agents"
        ],
        "operationId": "getPricingMarkdown",
        "summary": "Plans, per-seat prices, tier contents and pricing FAQ as markdown.",
        "description": "Generated from the same CMS content as the /pricing page, so a price edit lands in both at once.",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "content:read"
        ],
        "responses": {
          "200": {
            "description": "Markdown pricing sheet.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "tags": [
          "agents"
        ],
        "operationId": "callMcpServer",
        "summary": "Model Context Protocol server over Streamable HTTP.",
        "description": "JSON-RPC 2.0. Stateless: no session id, no handshake required,\nno credential. Supported methods: `initialize`, `ping`,\n`tools/list`, `tools/call`, `resources/list`, `resources/read`,\n`prompts/list`.\n\nTools: `search_content`, `get_page`, `list_pages`, `get_pricing`,\n`list_releases`, `list_developer_resources` — all read-only.\n\nMCP Apps: three tools name a `ui://` template in\n`_meta.ui.resourceUri`, readable via `resources/read`.\n\nManifest: https://goldenanalytics.com/.well-known/mcp.json",
        "security": [
          {}
        ],
        "x-required-scopes": [
          "content:read",
          "search:read"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response, or an array of them for a batch.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "202": {
            "description": "Body contained only notifications; no response."
          },
          "400": {
            "description": "Body is not valid JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/mcp.json": {
      "get": {
        "tags": [
          "agents"
        ],
        "operationId": "getMcpManifest",
        "summary": "MCP server manifest: transport, tools, and ui:// resources.",
        "security": [
          {}
        ],
        "responses": {
          "200": {
            "description": "Manifest.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/agent-skills/index.json": {
      "get": {
        "tags": [
          "agents"
        ],
        "operationId": "getAgentSkills",
        "summary": "Agent Skills index: every capability, with MCP and HTTP invocations.",
        "security": [
          {}
        ],
        "responses": {
          "200": {
            "description": "Skills index.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/oauth-protected-resource": {
      "get": {
        "tags": [
          "content"
        ],
        "operationId": "getProtectedResourceMetadata",
        "summary": "RFC 9728 protected-resource metadata, including scopes_supported.",
        "security": [
          {}
        ],
        "responses": {
          "200": {
            "description": "Resource metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "sanityWebhookSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "sanity-webhook-signature",
        "description": "HMAC-SHA256 signature over the raw request body, keyed with the shared webhook secret. Issued to the CMS only.",
        "x-scopes": {
          "cache:revalidate": "Invalidate the rendered-page cache. Sanity webhook only."
        }
      },
      "sanityPreviewSecret": {
        "type": "apiKey",
        "in": "query",
        "name": "sanity-preview-secret",
        "description": "Single-use preview secret minted by the CMS for an authenticated editor.",
        "x-scopes": {
          "draft:preview": "Enter draft-preview mode. Sanity Studio editors only."
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "status",
          "code",
          "message",
          "documentation_url"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable message (legacy alias of `message`)."
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code, repeated for convenience."
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code.",
            "enum": [
              "bad_request",
              "invalid_json",
              "validation_failed",
              "unauthorized",
              "forbidden",
              "not_found",
              "method_not_allowed",
              "not_acceptable",
              "rate_limited",
              "misconfigured",
              "upstream_error",
              "internal_error"
            ]
          },
          "message": {
            "type": "string"
          },
          "hint": {
            "type": "string",
            "description": "Concrete next step the caller can take."
          },
          "documentation_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "description": "Omit for a notification, which gets no response.",
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "method": {
            "type": "string",
            "enum": [
              "initialize",
              "ping",
              "tools/list",
              "tools/call",
              "resources/list",
              "resources/read",
              "prompts/list"
            ]
          },
          "params": {
            "type": "object"
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string"
          },
          "_type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "excerpt": {
            "type": "string"
          }
        }
      },
      "ContactSubmission": {
        "type": "object",
        "required": [
          "name",
          "email"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 200
          },
          "company": {
            "type": "string",
            "maxLength": 200
          },
          "message": {
            "type": "string",
            "maxLength": 5000
          },
          "intent": {
            "type": "string",
            "description": "Display label for the inquiry type."
          },
          "intentValue": {
            "type": "string",
            "description": "Stable routing key.",
            "enum": [
              "careers",
              "press",
              "partner",
              "sales",
              "support",
              ""
            ]
          },
          "company_website": {
            "type": "string",
            "description": "Honeypot. Must be empty."
          },
          "elapsedMs": {
            "type": "integer",
            "description": "Milliseconds between form mount and submit. Submissions under 3000ms are silently dropped."
          }
        }
      }
    }
  },
  "security": [
    {}
  ]
}