{
  "openapi": "3.0.3",
  "info": {
    "title": "SlydeDeck API",
    "version": "1.1.0",
    "description": "Public, AI-agent-friendly API for the SlydeDeck presentation sharing platform. List public presentations and retrieve their metadata and AI-generated summaries. Read-only public access requires no authentication. This spec is served at both /openapi.json and /api/docs.",
    "contact": { "name": "SlydeDeck Support", "url": "https://slydedeck.com/contact" },
    "license": { "name": "Proprietary", "url": "https://slydedeck.com/terms" }
  },
  "servers": [
    { "url": "https://slydedeck.com/api", "description": "Production" }
  ],
  "externalDocs": {
    "description": "AI agent integration guide",
    "url": "https://slydedeck.com/llms.txt"
  },
  "tags": [
    { "name": "Decks", "description": "Public presentations and their AI summaries" },
    { "name": "System", "description": "Operational status endpoints" }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Session token obtained via OAuth login. Required only for write operations."
      }
    },
    "schemas": {
      "Deck": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Unique deck identifier", "example": "ckz1a2b3c4d5" },
          "title": { "type": "string", "description": "Presentation title", "example": "Quarterly Product Review" },
          "description": { "type": "string", "nullable": true, "example": "Q3 roadmap and metrics" },
          "presentationCode": { "type": "string", "description": "Short public share code", "example": "ABC123" },
          "presenterName": { "type": "string", "example": "Jane Doe" },
          "tags": { "type": "array", "items": { "type": "string" }, "example": ["product", "roadmap"] },
          "isLive": { "type": "boolean", "example": true },
          "viewCount": { "type": "integer", "example": 142 },
          "createdAt": { "type": "string", "format": "date-time", "example": "2026-06-01T12:00:00.000Z" },
          "highLevelSummary": { "type": "string", "nullable": true, "description": "AI-generated overview", "example": "This deck covers the Q3 product roadmap..." }
        },
        "required": ["id", "title", "presentationCode", "isLive"]
      },
      "DeckList": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "decks": { "type": "array", "items": { "$ref": "#/components/schemas/Deck" } },
              "total": { "type": "integer", "example": 57 },
              "limit": { "type": "integer", "example": 20 },
              "offset": { "type": "integer", "example": 0 }
            }
          }
        }
      },
      "Problem": {
        "type": "object",
        "description": "RFC 7807 Problem Details",
        "properties": {
          "type": { "type": "string", "format": "uri", "example": "https://slydedeck.com/errors/not-found" },
          "title": { "type": "string", "example": "Resource Not Found" },
          "status": { "type": "integer", "example": 404 },
          "detail": { "type": "string", "example": "No public deck found for the given ID or share code." },
          "instance": { "type": "string", "example": "/api/decks/UNKNOWN" }
        }
      },
      "Status": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["operational", "degraded", "down"], "example": "operational" },
          "api": { "type": "string", "example": "SlydeDeck API v1.0" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      }
    },
    "responses": {
      "Problem404": {
        "description": "Resource not found",
        "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }
      },
      "Problem401": {
        "description": "Authentication required",
        "headers": {
          "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge" }
        },
        "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }
      },
      "Problem500": {
        "description": "Server error",
        "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }
      }
    }
  },
  "paths": {
    "/decks": {
      "get": {
        "summary": "List public decks",
        "description": "Returns a paginated list of publicly live presentations. No authentication required.",
        "operationId": "listDecks",
        "tags": ["Decks"],
        "x-ai-description": "List public, live presentations. No auth required. Use to discover available decks before fetching one by ID.",
        "x-ai-example-prompt": "Show me the latest public presentations on SlydeDeck",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 }, "description": "Number of results to return" },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of public decks",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DeckList" },
                "example": {
                  "success": true,
                  "data": {
                    "decks": [
                      { "id": "ckz1a2b3c4d5", "title": "Quarterly Product Review", "description": "Q3 roadmap and metrics", "presentationCode": "ABC123", "presenterName": "Jane Doe", "tags": ["product", "roadmap"], "isLive": true, "viewCount": 142, "createdAt": "2026-06-01T12:00:00.000Z", "highLevelSummary": "This deck covers the Q3 product roadmap..." }
                    ],
                    "total": 57, "limit": 20, "offset": 0
                  }
                }
              }
            }
          },
          "500": { "$ref": "#/components/responses/Problem500" }
        }
      },
      "post": {
        "summary": "Create a deck",
        "description": "Upload a new presentation. Requires authentication.",
        "operationId": "createDeck",
        "tags": ["Decks"],
        "security": [{ "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title"],
                "properties": {
                  "title": { "type": "string", "example": "My Presentation" },
                  "description": { "type": "string", "example": "An overview deck" },
                  "tags": { "type": "array", "items": { "type": "string" }, "example": ["demo"] },
                  "isLive": { "type": "boolean", "default": false }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Deck created",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Deck" } } } } }
          },
          "401": { "$ref": "#/components/responses/Problem401" },
          "422": { "$ref": "#/components/responses/Problem404" }
        }
      }
    },
    "/decks/{id}": {
      "get": {
        "summary": "Get a deck by ID or share code",
        "description": "Returns metadata and AI summary for a single public presentation. For plain-text, LLM-optimized content use ?format=llm or send header Accept: text/plain.",
        "operationId": "getDeck",
        "tags": ["Decks"],
        "x-ai-description": "Fetch one public deck by ID or share code, including its AI-generated summary. Append ?format=llm (or send Accept: text/plain) for readable plain text instead of JSON.",
        "x-ai-example-prompt": "Summarize the SlydeDeck presentation with share code ABC123",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Presentation ID or share code", "example": "ABC123" },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json", "llm"] }, "description": "Use format=llm for plain-text AI-friendly content" },
          { "name": "Accept", "in": "header", "schema": { "type": "string", "enum": ["application/json", "text/plain"] }, "description": "Send text/plain to receive LLM-optimized plain text (same as ?format=llm)" }
        ],
        "responses": {
          "200": {
            "description": "Deck found",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Deck" } } },
                "example": { "success": true, "data": { "id": "ckz1a2b3c4d5", "title": "Quarterly Product Review", "presentationCode": "ABC123", "presenterName": "Jane Doe", "tags": ["product"], "isLive": true, "viewCount": 142, "createdAt": "2026-06-01T12:00:00.000Z", "highLevelSummary": "This deck covers the Q3 product roadmap..." } }
              },
              "text/plain": {
                "schema": { "type": "string" },
                "example": "Title: Quarterly Product Review\nPresenter: Jane Doe\nTags: product\n\nSummary:\nThis deck covers the Q3 product roadmap..."
              }
            }
          },
          "404": { "$ref": "#/components/responses/Problem404" },
          "500": { "$ref": "#/components/responses/Problem500" }
        }
      }
    },
    "/status": {
      "get": {
        "summary": "API status",
        "description": "Returns current API operational status. No authentication required.",
        "operationId": "getStatus",
        "tags": ["System"],
        "x-ai-description": "Public operational status of the API. No auth required.",
        "responses": {
          "200": {
            "description": "API is operational",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" }, "example": { "status": "operational", "api": "SlydeDeck API v1.0", "timestamp": "2026-06-28T00:00:00.000Z" } } }
          }
        }
      }
    },
    "/docs": {
      "get": {
        "summary": "Machine-readable OpenAPI specification",
        "description": "Returns this OpenAPI 3 document as JSON.",
        "operationId": "getDocs",
        "tags": ["System"],
        "responses": { "200": { "description": "OpenAPI specification" } }
      }
    }
  }
}