{
  "openapi": "3.1.0",
  "info": {
    "title": "Vespper DOCX API",
    "description": "Read and edit Microsoft Word (.docx) documents. Edits are applied as Word tracked changes (suggestions), never silent overwrites.",
    "version": "0.1.0"
  },
  "paths": {
    "/v1/docx/read": {
      "post": {
        "tags": [
          "docx"
        ],
        "summary": "Read Docx",
        "description": "Receive a .docx and return its HTML projection.",
        "operationId": "read_docx_v1_docx_read_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_read_docx_v1_docx_read_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "HTML projection of the document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "html": {
                      "type": "string"
                    },
                    "approx_tokens": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "html",
                    "approx_tokens"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/v1/docx/edit": {
      "post": {
        "tags": [
          "docx"
        ],
        "summary": "Edit Docx",
        "description": "Receive a .docx + a JSON array of `{old, new}` HTML edits and return the\npatched .docx with ALL edits applied as tracked changes. The edits are\nlocalized, checked for overlap (each replaces a whole block, so anchors must\nnot overlap), reconciled IN PARALLEL, then merged into one document. A single\nedit is just a one-element array. The ``author`` field is stamped on every\nnew tracked change (and passed to the reconciler for existing-TC handling).\nResponse headers include `X-Edit-Count` (number of edits) and reconciler token\ntotals (`X-Total-Tokens`, etc.) for gateway metering.",
        "operationId": "edit_docx_v1_docx_edit_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_edit_docx_v1_docx_edit_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Edited .docx with tracked changes applied",
            "headers": {
              "X-Edit-Count": {
                "schema": {
                  "type": "integer"
                },
                "description": "Number of edits applied"
              },
              "X-Total-Tokens": {
                "schema": {
                  "type": "integer"
                },
                "description": "Reconciler LLM token usage"
              }
            },
            "content": {
              "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Body_edit_docx_v1_docx_edit_post": {
        "properties": {
          "file": {
            "type": "string",
            "contentMediaType": "application/octet-stream",
            "title": "File"
          },
          "edits": {
            "type": "string",
            "title": "Edits"
          },
          "author": {
            "type": "string",
            "title": "Author",
            "description": "Tracked-change author name (shown in Word Review)"
          }
        },
        "type": "object",
        "required": [
          "file",
          "edits",
          "author"
        ],
        "title": "Body_edit_docx_v1_docx_edit_post"
      },
      "Body_read_docx_v1_docx_read_post": {
        "properties": {
          "file": {
            "type": "string",
            "contentMediaType": "application/octet-stream",
            "title": "File"
          }
        },
        "type": "object",
        "required": [
          "file"
        ],
        "title": "Body_read_docx_v1_docx_read_post"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from the developer dashboard (`sk_live_...`)."
      }
    }
  },
  "servers": [
    {
      "url": "https://api.vespper.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ]
}