{
  "openapi": "3.1.0",
  "info": {
    "title": "Sidefold Public Discovery API",
    "version": "1.0.0",
    "description": "Safe, read-only discovery of public Sidefold creators and publications. Publishing requires creator authentication and an explicit Google Doc selection. Purchases require human confirmation in the Sidefold checkout flow.",
    "contact": { "name": "Sidefold", "email": "hello@sidefold.co", "url": "https://sidefold.co/contact" }
  },
  "servers": [{ "url": "https://api.sidefold.co" }],
  "paths": {
    "/healthz": {
      "get": {
        "operationId": "getServiceHealth",
        "summary": "Check API availability",
        "responses": { "200": { "description": "Service is available", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" } }, "required": ["status"] } } } } }
      }
    },
    "/v1/seo/publications": {
      "get": {
        "operationId": "listPublicPublicationPages",
        "summary": "List canonical public publication pages",
        "description": "Returns the creator username, publication slug, and last update time for published Sidefold books.",
        "responses": { "200": { "description": "Public publication page index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPageIndex" } } } } }
      }
    },
    "/v1/creators/{username}": {
      "get": {
        "operationId": "getPublicCreator",
        "summary": "Get a public creator profile",
        "parameters": [{ "$ref": "#/components/parameters/Username" }],
        "responses": {
          "200": { "description": "Creator and published books", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Creator" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/creators/{username}/publications/{slug}": {
      "get": {
        "operationId": "getPublicPublication",
        "summary": "Get public storefront metadata and preview content",
        "parameters": [{ "$ref": "#/components/parameters/Username" }, { "$ref": "#/components/parameters/Slug" }],
        "responses": {
          "200": { "description": "Published book metadata, offer, contents, and excerpt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Publication" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Username": { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Canonical Sidefold creator username" },
      "Slug": { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Canonical publication slug" }
    },
    "responses": {
      "NotFound": { "description": "Creator or publication was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "PublicPageIndex": {
        "type": "object",
        "properties": { "pages": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "slug": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": ["username", "slug", "updatedAt"] } } },
        "required": ["pages"]
      },
      "Creator": {
        "type": "object",
        "properties": { "username": { "type": "string" }, "name": { "type": "string" }, "picture": { "type": "string", "format": "uri" }, "instagramUsername": { "type": "string" }, "publications": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "author": { "type": "string" }, "priceCents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["slug", "title", "author", "priceCents", "currency"] } } },
        "required": ["username", "name", "publications"]
      },
      "Publication": {
        "type": "object",
        "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "author": { "type": "string" }, "description": { "type": "string" }, "isbn": { "type": "string" }, "priceCents": { "type": "integer" }, "salePriceCents": { "type": "integer" }, "currency": { "type": "string" }, "availableFormats": { "type": "array", "items": { "type": "string" } }, "checkoutAvailable": { "type": "boolean" }, "lastSyncedAt": { "type": "string", "format": "date-time" } },
        "required": ["id", "username", "slug", "title", "author", "priceCents", "currency", "availableFormats", "checkoutAvailable"]
      },
      "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }
    }
  }
}