{
  "openapi": "3.1.0",
  "info": {
    "title": "Pangram File Upload API",
    "version": "1.0.0",
    "description": "Upload files for AI detection and dashboard-backed results."
  },
  "servers": [
    {
      "url": "https://file-external.api.pangram.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    },
    "schemas": {
      "FileUploadResult": {
        "type": "object",
        "properties": {
          "public_dashboard_link": {
            "type": "string",
            "format": "uri",
            "description": "Public dashboard URL for the uploaded file."
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "loc": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "msg": {
                  "type": "string"
                },
                "input": {}
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/": {
      "post": {
        "summary": "Upload files",
        "description": "Upload one or more files as multipart form data for AI detection.",
        "operationId": "uploadFiles",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl -s -X POST https://file-external.api.pangram.com \\\n  -H \"x-api-key: $PANGRAM_API_KEY\" \\\n  -F \"files=@modeling/deployments/test/test_document.docx\" \\\n  -F \"public_dashboard_link=true\""
          }
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["files"],
                "properties": {
                  "files": {
                    "type": "array",
                    "description": "Files to analyze. Send this form field once per uploaded file.",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    }
                  },
                  "public_dashboard_link": {
                    "type": "boolean",
                    "description": "Whether to create and return a public dashboard link for each uploaded file.",
                    "default": false
                  }
                }
              },
              "encoding": {
                "files": {
                  "style": "form",
                  "explode": true,
                  "contentType": "application/octet-stream"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-file upload results.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/FileUploadResult"
                  }
                },
                "example": [
                  {
                    "public_dashboard_link": "https://www.pangram.com/history/123e4567-e89b-12d3-a456-426614174000"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "The multipart request is missing a file or includes invalid form data."
          },
          "401": {
            "description": "The x-api-key is missing or invalid."
          },
          "402": {
            "description": "The account has insufficient credits."
          },
          "413": {
            "description": "The upload exceeds the maximum supported file size."
          },
          "415": {
            "description": "The uploaded file type is not supported."
          },
          "422": {
            "description": "The files field is missing, the form data is invalid, or Pangram could not extract valid text from the uploaded file.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                },
                "example": {
                  "detail": [
                    {
                      "type": "missing",
                      "loc": ["body", "files"],
                      "msg": "Field required",
                      "input": null
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "There was an error processing the upload."
          }
        }
      }
    }
  }
}