{
  "openapi": "3.1.0",
  "info": {
    "title": "PostPaper API",
    "description": "API for reading and editing collaborative documents in PostPaper. Use these endpoints to read document content, append text, or replace entire documents.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://postpaper.co",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/v1/docs/{docId}/text": {
      "get": {
        "operationId": "readDocument",
        "summary": "Read document content as plain text/markdown",
        "description": "Returns the full content of a document as plain text with markdown formatting. Headings use #, bullet lists use -, numbered lists use 1.",
        "parameters": [
          {
            "name": "docId",
            "in": "path",
            "required": true,
            "description": "The document ID (from the URL, e.g. for https://postpaper.co/doc/abc123 the docId is abc123)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Document content",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "content": {
                      "type": "string",
                      "description": "The document content as markdown text"
                    },
                    "blockCount": {
                      "type": "integer",
                      "description": "Number of blocks in the document"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "appendToDocument",
        "summary": "Append text to the end of a document",
        "description": "Adds new content to the end of the document without deleting existing content. Send a JSON object with a 'content' field containing markdown text. Lines starting with # become headings, - become bullet lists, 1. become numbered lists, everything else becomes paragraphs. Use \\n for newlines.",
        "parameters": [
          {
            "name": "docId",
            "in": "path",
            "required": true,
            "description": "The document ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["content"],
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "The markdown text to append. Use \\n for newlines. Example: \"# Heading\\nSome paragraph\\n- Bullet point\""
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "blocksAppended": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "replaceDocument",
        "summary": "Replace entire document content",
        "description": "Deletes all existing content and replaces it with the provided text. Send a JSON object with a 'content' field containing markdown. Use \\n for newlines. # for headings, - for bullets, 1. for numbered lists.",
        "parameters": [
          {
            "name": "docId",
            "in": "path",
            "required": true,
            "description": "The document ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["content"],
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "The markdown text to write. Use \\n for newlines. Example: \"# Title\\nParagraph text\\n- Item 1\\n- Item 2\""
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "blocksWritten": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}