{
  "openapi": "3.1.0",
  "info": {
    "title": "Prompt Pivot Pitch Problem API",
    "version": "1.0.0",
    "description": "API-first contract for problem shaping, public cards, safe share copy, and agent discovery."
  },
  "servers": [{ "url": "https://prompt-pivot-pitch.com/api" }],
  "paths": {
    "/problem/v1/schema": {
      "get": {
        "operationId": "ppp_get_problem_schema",
        "summary": "Get public problem-card schema",
        "responses": { "200": { "description": "JSON Schema for public problem cards" } }
      }
    },
    "/problem/v1/criteria": {
      "get": {
        "operationId": "ppp_get_criteria",
        "summary": "Get problem-shaping criteria",
        "responses": { "200": { "description": "Problem categories, checks, and constraints" } }
      }
    },
    "/problem/v1/shape-preview": {
      "post": {
        "operationId": "ppp_shape_problem",
        "summary": "Shape source material into public/private outputs",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProblemShaperInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic problem-shaper preview",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProblemShaperResult" }
              }
            }
          }
        }
      }
    },
    "/problem/v1/submit": {
      "post": {
        "operationId": "ppp_submit_problem",
        "summary": "Submit a problem",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProblemSubmissionInput" }
            }
          }
        },
        "responses": { "201": { "description": "Problem submitted" } }
      }
    },
    "/problem/v1/submissions/{id}/status": {
      "get": {
        "operationId": "ppp_get_submission_status",
        "summary": "Get public submission status",
        "parameters": [{ "$ref": "#/components/parameters/SubmissionId" }],
        "responses": { "200": { "description": "Public submission status without private pledge totals" } }
      }
    },
    "/problem/v1/submissions/{id}/public-card": {
      "get": {
        "operationId": "ppp_get_public_card",
        "summary": "Get public card",
        "parameters": [{ "$ref": "#/components/parameters/SubmissionId" }],
        "responses": { "200": { "description": "Public-safe problem card and Markdown" } }
      }
    },
    "/problem/v1/submissions/{id}/share-copy": {
      "get": {
        "operationId": "ppp_get_share_copy",
        "summary": "Get public-safe share copy",
        "parameters": [{ "$ref": "#/components/parameters/SubmissionId" }],
        "responses": { "200": { "description": "Share copy" } }
      }
    },
    "/problem/v1/submissions/{id}/pledge-signal": {
      "get": {
        "operationId": "ppp_get_pledge_signal",
        "summary": "Get public-safe vote and pledge signals",
        "parameters": [{ "$ref": "#/components/parameters/SubmissionId" }],
        "responses": {
          "200": {
            "description": "Safe signal without raw pledge totals",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SafeSignal" }
              }
            }
          }
        }
      }
    },
    "/problems": {
      "get": {
        "operationId": "ppp_list_public_problems",
        "summary": "List public problem submissions",
        "responses": {
          "200": {
            "description": "Public problem board",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "problems": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ProblemSubmission" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/problems/{id}": {
      "get": {
        "operationId": "ppp_get_public_problem",
        "summary": "Get one public problem submission",
        "parameters": [{ "$ref": "#/components/parameters/SubmissionId" }],
        "responses": { "200": { "description": "Public problem submission" } }
      },
      "patch": {
        "operationId": "ppp_update_owned_problem",
        "summary": "Update an owned problem using a private manage token",
        "parameters": [
          { "$ref": "#/components/parameters/SubmissionId" },
          { "$ref": "#/components/parameters/BearerManageToken" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProblemUpdateInput" }
            }
          }
        },
        "responses": {
          "200": { "description": "Problem updated" },
          "401": { "description": "Manage token required" },
          "404": { "description": "Problem not found or token invalid" }
        }
      }
    },
    "/problems/{id}/archive-request": {
      "post": {
        "operationId": "ppp_request_problem_archive",
        "summary": "Request organizer-approved archive for an owned problem",
        "parameters": [
          { "$ref": "#/components/parameters/SubmissionId" },
          { "$ref": "#/components/parameters/BearerManageToken" }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": { "reason": { "type": "string", "maxLength": 1000 } }
              }
            }
          }
        },
        "responses": {
          "202": { "description": "Archive request sent to organizer" },
          "401": { "description": "Manage token required" },
          "404": { "description": "Problem not found or token invalid" }
        }
      }
    },
    "/agent/v1/discover": {
      "get": {
        "operationId": "ppp_agent_discover",
        "summary": "Discover agent-readable docs and tools",
        "responses": { "200": { "description": "Agent discovery document" } }
      }
    },
    "/agent/v1/bootstrap": {
      "get": {
        "operationId": "ppp_get_externa_bootstrap",
        "summary": "Get paste-to-provision Externa Bootstrap prompt",
        "parameters": [
          { "name": "submissionId", "in": "query", "schema": { "type": "string" } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["markdown"] } }
        ],
        "responses": {
          "200": {
            "description": "Bootstrap payload with paste_blob",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ExternaBootstrapPayload" }
              }
            }
          }
        }
      }
    },
    "/agent/v1/bootstrap/files": {
      "get": {
        "operationId": "ppp_get_externa_bootstrap_files",
        "summary": "Get Externa Bootstrap file templates",
        "parameters": [{ "name": "submissionId", "in": "query", "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Bootstrap files" } }
      }
    },
    "/agent/v1/bootstrap/preview": {
      "get": {
        "operationId": "ppp_get_externa_bootstrap_preview",
        "summary": "Preview Externa Bootstrap outcome",
        "parameters": [{ "name": "submissionId", "in": "query", "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Bootstrap preview" } }
      }
    },
    "/agent/v1/llmcopy": {
      "get": {
        "operationId": "ppp_get_llmcopy",
        "summary": "Get LLMCopy paste blob and docs",
        "parameters": [{ "name": "submissionId", "in": "query", "schema": { "type": "string" } }],
        "responses": { "200": { "description": "LLMCopy payload" } }
      }
    },
    "/agent/mcp/manifest": {
      "get": {
        "operationId": "ppp_mcp_manifest",
        "summary": "Get MCP-ready manifest preview",
        "responses": { "200": { "description": "MCP manifest preview" } }
      }
    }
  },
  "components": {
    "parameters": {
      "SubmissionId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": { "type": "string" }
      },
      "BearerManageToken": {
        "name": "Authorization",
        "in": "header",
        "required": true,
        "description": "Bearer token from the private manage link email.",
        "schema": { "type": "string", "pattern": "^Bearer\\s+.+" }
      }
    },
    "schemas": {
      "ProblemShaperInput": {
        "type": "object",
        "required": ["source", "sourceMaterial"],
        "properties": {
          "source": { "type": "string", "enum": ["shape_with_ai", "copy_for_llm", "manual", "agent_api"] },
          "sourceMaterial": { "type": "string", "minLength": 20 },
          "title": { "type": "string" },
          "category": { "$ref": "#/components/schemas/FiveP" },
          "affectedAudience": { "type": "string" },
          "todaysState": { "type": "string" },
          "desiredOutcome": { "type": "string" }
        }
      },
      "ProblemSubmissionInput": {
        "type": "object",
        "required": ["title", "category", "ownerName", "ownerEmail", "description"],
        "properties": {
          "title": { "type": "string" },
          "category": { "$ref": "#/components/schemas/FiveP" },
          "ownerName": { "type": "string" },
          "ownerEmail": { "type": "string", "format": "email" },
          "company": { "type": "string" },
          "description": { "type": "string", "minLength": 30 },
          "affectedAudience": { "type": "string" },
          "currentCost": { "type": "string" },
          "desiredOutcome": { "type": "string" },
          "pledgeAmount": { "type": "number", "minimum": 0 }
        }
      },
      "ProblemUpdateInput": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "category": { "$ref": "#/components/schemas/FiveP" },
          "ownerName": { "type": "string" },
          "company": { "type": "string" },
          "description": { "type": "string", "minLength": 30 },
          "affectedAudience": { "type": "string" },
          "currentCost": { "type": "string" },
          "desiredOutcome": { "type": "string" },
          "pledgeAmount": { "type": "number", "minimum": 0 }
        }
      },
      "ProblemSubmission": {
        "allOf": [
          { "$ref": "#/components/schemas/ProblemSubmissionInput" },
          {
            "type": "object",
            "required": ["id", "status", "voteCount", "pledgedAmount", "createdAt", "updatedAt"],
            "properties": {
              "id": { "type": "string" },
              "status": {
                "type": "string",
                "enum": ["submitted", "shortlisted", "selected", "archived", "archive_requested"]
              },
              "voteCount": { "type": "number", "minimum": 0 },
              "pledgedAmount": { "type": "number", "minimum": 0 },
              "createdAt": { "type": "string", "format": "date-time" },
              "updatedAt": { "type": "string", "format": "date-time" },
              "archivedAt": { "type": "string", "format": "date-time" },
              "archiveRequestedAt": { "type": "string", "format": "date-time" }
            }
          }
        ]
      },
      "ProblemShaperResult": {
        "type": "object",
        "required": ["version", "source", "sourceMaterial", "publicCard", "privateReadiness", "submissionPayload", "shareCopy", "unresolvedQuestion", "publicSafety"],
        "properties": {
          "version": { "type": "string", "const": "1.0" },
          "source": { "type": "string" },
          "sourceMaterial": { "type": "string" },
          "publicCard": { "$ref": "https://prompt-pivot-pitch.com/problem-card-schema.json" },
          "privateReadiness": { "type": "object" },
          "submissionPayload": { "$ref": "#/components/schemas/ProblemSubmissionInput" },
          "shareCopy": { "type": "object" },
          "unresolvedQuestion": { "type": "string" },
          "publicSafety": { "type": "object" }
        }
      },
      "SafeSignal": {
        "type": "object",
        "required": ["submissionId", "pledgeSignal", "voteSignal", "publicSummary", "privateDetailsAvailable"],
        "properties": {
          "submissionId": { "type": "string" },
          "pledgeSignal": { "type": "string", "enum": ["none", "interest", "pilot_interest", "sponsor_interest", "private"] },
          "voteSignal": { "type": "string", "enum": ["none", "early_interest", "active_interest", "strong_interest"] },
          "publicSummary": { "type": "string" },
          "privateDetailsAvailable": { "type": "boolean" }
        }
      },
      "ExternaBootstrapPayload": {
        "type": "object",
        "required": ["schema_version", "brand", "event", "mode", "paste_blob"],
        "properties": {
          "schema_version": { "type": "string", "const": "ppp_externa_bootstrap_v1" },
          "brand": { "type": "string", "const": "Externa" },
          "event": { "type": "string", "const": "Prompt Pivot Pitch" },
          "mode": { "type": "string", "const": "paste_to_provision" },
          "paste_blob": { "type": "string" }
        }
      },
      "FiveP": {
        "type": "string",
        "enum": ["People", "Product", "Process", "Profit", "Purpose"]
      }
    }
  }
}