{
  "openapi": "3.1.0",
  "info": {
    "title": "SuperDoc API",
    "description": "High-performance document conversion API. Convert DOCX files to PDF with excellent Microsoft Word compatibility.",
    "version": "1.0.0",
    "contact": {
      "name": "SuperDoc API Support",
      "email": "api@superdoc.dev",
      "url": "https://superdoc.dev"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://api.superdoc.dev",
      "description": "Production server"
    },
    {
      "url": "https://api-staging.superdoc.dev",
      "description": "Staging server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "Get API Information",
        "description": "Returns information about the API including version, available endpoints, and service status.",
        "operationId": "getApiInfo",
        "security": [],
        "responses": {
          "200": {
            "description": "API information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiInfo"
                }
              }
            }
          }
        },
        "tags": [
          "General"
        ]
      }
    },
    "/v1/health": {
      "get": {
        "summary": "Health Check",
        "description": "Check the health and status of the API service.",
        "operationId": "healthCheck",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "General"
        ]
      }
    },
    "/v1/convert": {
      "post": {
        "summary": "Convert Document to PDF",
        "description": "Convert a DOCX file to PDF format. Requires authentication.",
        "operationId": "convertToPdf",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "DOCX file to convert (max 25MB)"
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "description": "Output format (currently only 'pdf' is supported)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pdf"
              ],
              "default": "pdf"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully converted document",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            },
            "headers": {
              "Content-Disposition": {
                "description": "Attachment filename",
                "schema": {
                  "type": "string",
                  "example": "attachment; filename=\"document.pdf\""
                }
              },
              "X-RateLimit-Limit": {
                "description": "Request limit per hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Requests remaining in current window",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "Unix timestamp when rate limit resets",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "Bad request (invalid file, format, etc.)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized (invalid or missing API key)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "File too large (exceeds 25MB limit)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitErrorResponse"
                }
              }
            },
            "headers": {
              "X-RateLimit-Retry-After": {
                "description": "Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Conversion"
        ]
      }
    },
    "/v1/public/convert": {
      "post": {
        "summary": "Public Document Conversion",
        "description": "Convert a DOCX file to PDF without authentication. Rate limited to 10 requests per hour with 5MB file size limit.",
        "operationId": "publicConvert",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "DOCX file to convert (max 5MB for public endpoint)"
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "description": "Output format (currently only 'pdf' is supported)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pdf"
              ],
              "default": "pdf"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully converted document",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            },
            "headers": {
              "Content-Disposition": {
                "description": "Attachment filename",
                "schema": {
                  "type": "string"
                }
              },
              "X-RateLimit-Limit": {
                "description": "Request limit per hour (10 for public)",
                "schema": {
                  "type": "integer",
                  "example": 10
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Requests remaining in current window",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "File too large (exceeds 5MB limit for public endpoint)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (10 requests per hour for public)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Conversion"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "API key authentication. Format: `Bearer sd_live_pk_your_api_key`"
      }
    },
    "schemas": {
      "ApiInfo": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "SuperDoc API"
          },
          "version": {
            "type": "string",
            "example": "1.0.0"
          },
          "description": {
            "type": "string",
            "example": "High-performance document conversion API"
          },
          "endpoints": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "/v1/convert",
              "/v1/public/convert",
              "/v1/health"
            ]
          },
          "documentation": {
            "type": "string",
            "example": "https://docs.superdoc.dev"
          }
        },
        "required": [
          "name",
          "version",
          "endpoints"
        ]
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "degraded",
              "down"
            ],
            "example": "ok"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2024-01-15T10:30:00Z"
          },
          "checks": {
            "type": "object",
            "properties": {
              "database": {
                "type": "boolean",
                "example": true
              },
              "storage": {
                "type": "boolean",
                "example": true
              },
              "conversion": {
                "type": "boolean",
                "example": true
              }
            }
          }
        },
        "required": [
          "status",
          "timestamp"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Machine-readable error code",
            "example": "INVALID_FILE_TYPE"
          },
          "error": {
            "type": "string",
            "description": "HTTP error type",
            "example": "Bad Request"
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message",
            "example": "Only DOCX files are supported for conversion"
          },
          "requestId": {
            "type": "string",
            "description": "Unique request identifier for support",
            "example": "req_abc123def456"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2024-01-15T10:30:00Z"
          }
        },
        "required": [
          "code",
          "error",
          "message",
          "requestId"
        ]
      },
      "RateLimitErrorResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorResponse"
          },
          {
            "type": "object",
            "properties": {
              "retryAfter": {
                "type": "integer",
                "description": "Seconds to wait before retrying",
                "example": 3600
              }
            },
            "required": [
              "retryAfter"
            ]
          }
        ]
      }
    }
  },
  "tags": [
    {
      "name": "General",
      "description": "General API information and health checks"
    },
    {
      "name": "Conversion",
      "description": "Document conversion endpoints"
    }
  ]
}