@apifreaks/openapi-specs 0.1.0

package/specs/pdf/pdf-files.json

@@ -0,0 +1,126 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "PDF Files API Reference",
+    "version": "1.0.0",
+    "description": "Retrieve a list of all PDF files uploaded and generated by a user. Returns an array of file objects with file ID and file name. Note: Organization members cannot access this endpoint — only the Organization Administrator can.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "PDF Files API Server"
+    }
+  ],
+  "paths": {
+    "/pdf/files": {
+      "get": {
+        "tags": ["Task Status and File Info APIs"],
+        "summary": "Get list of PDF files",
+        "description": "This API retrieves a list of all PDF files uploaded and generated by a specific user. Please note that if the user is part of an organization, only the Organization Administrator can access this endpoint. Organization Members cannot access this endpoint.",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            },
+            "description": "Specifies the desired format for the API response. Choose 'json' for a JSON object or 'xml' for an XML structure."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PdfFileListResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "File list",
+                    "value": {
+                      "files": [
+                        {
+                          "fileId": "abc123",
+                          "fileName": "document.pdf"
+                        },
+                        {
+                          "fileId": "def456",
+                          "fileName": "report.pdf"
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "operationId": "getFiles"
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "PdfFileListResponse": {
+        "type": "object",
+        "description": "PDF file list response containing an array of file objects.",
+        "required": ["files"],
+        "properties": {
+          "files": {
+            "type": "array",
+            "description": "List of files available on the server.",
+            "items": {
+              "$ref": "#/components/schemas/PdfFileItem"
+            }
+          }
+        }
+      },
+      "PdfFileItem": {
+        "type": "object",
+        "description": "A single PDF file in the file list.",
+        "properties": {
+          "fileId": {
+            "type": "string",
+            "description": "Unique ID for the file, used to fetch or process the file."
+          },
+          "fileName": {
+            "type": "string",
+            "description": "Original name of the uploaded file."
+          }
+        },
+        "required": []
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}

package/specs/pdf/pdf-resource-download.json

@@ -0,0 +1,168 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "PDF Resource Download API Reference",
+    "version": "1.0.0",
+    "description": "Download PDF files or ZIP archives from the server using their unique resource ID. Returns the file as a binary stream for direct download. Supports PDF and ZIP output formats depending on the requested resource.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "PDF Resource Download API Server"
+    }
+  ],
+  "paths": {
+    "/pdf/resource/download": {
+      "get": {
+        "tags": ["PDF Upload and Download APIs"],
+        "summary": "Download PDF resource",
+        "description": "This API downloads PDF files or ZIP archives from the server using their unique resource ID.",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            },
+            "description": "Response format: 'json' (default) or 'xml'."
+          },
+          {
+            "name": "resource_id",
+            "in": "query",
+            "description": "The unique identifier of the file or ZIP archive to download.",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "File download successful. Returns the raw file bytes with Content-Disposition: attachment, not a JSON body.",
+            "content": {
+              "application/pdf": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "application/zip": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Missing required resource_id parameter",
+            "content": {
+              "application/json": {
+                "examples": {
+                  "missingResourceId": {
+                    "summary": "Missing resource_id parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/pdf/resource/download",
+                      "status": 400,
+                      "timestamp": "2026-07-27T10:47:12.356Z"
+                    }
+                  }
+                },
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Resource ID Not Found",
+            "content": {
+              "application/json": {
+                "examples": {
+                  "error": {
+                    "summary": "Resource ID not found",
+                    "value": {
+                      "timestamp": "2026-07-27T10:47:12.926Z",
+                      "path": "/v1.0/pdf/resource",
+                      "status": 404,
+                      "error": "Resource ID Not Found",
+                      "message": "Please provide a valid resource ID."
+                    }
+                  }
+                },
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "operationId": "downloadResource"
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}

package/specs/pdf/pdf-resource-upload-binary.json

@@ -0,0 +1,218 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "PDF Binary Resource Upload API Reference",
+    "version": "1.0.0",
+    "description": "Upload a PDF file as raw binary data in the request body. Returns file metadata including the file ID, file name, size, and type. This endpoint accepts the raw file bytes directly instead of multipart form-data.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "PDF Binary Resource Upload API Server"
+    }
+  ],
+  "paths": {
+    "/pdf/resource/upload-binary": {
+      "post": {
+        "tags": [
+          "PDF Upload and Download APIs"
+        ],
+        "summary": "Upload a PDF in binary format",
+        "description": "This API uploads PDF files to the API Freaks server in binary format.",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "json",
+                "xml"
+              ],
+              "default": "json"
+            },
+            "description": "Specifies the desired format for the API response. Choose 'json' for a JSON object or 'xml' for an XML structure."
+          },
+          {
+            "name": "file_name",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "The desired name for the uploaded PDF file. This name will be used for storage on the server.\n\n\n **NOTE**: Please ensure file_name has extension `.pdf`."
+          }
+        ],
+        "requestBody": {
+          "description": "Raw PDF file bytes sent directly as the request body (not multipart).",
+          "required": true,
+          "content": {
+            "application/octet-stream": {
+              "schema": {
+                "type": "string",
+                "format": "binary",
+                "description": "The PDF file to be uploaded to the API Freaks server in binary format."
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "PDF upload successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BinaryResourceUploadResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "File uploaded",
+                    "value": {
+                      "fileName": "binarytest.pdf",
+                      "fileId": "b0fbf78c-8fe2-49b6-ad3d-63efb4ac8e58"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request \u2014 Missing file_name or empty body",
+            "content": {
+              "application/json": {
+                "examples": {
+                  "missingFileName": {
+                    "summary": "Missing file_name query parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/pdf/resource/upload-binary",
+                      "status": 400,
+                      "timestamp": "2026-07-27T10:48:14.902Z"
+                    }
+                  },
+                  "emptyBody": {
+                    "summary": "Empty request body",
+                    "value": {
+                      "timestamp": "2026-07-27T10:48:16.046Z",
+                      "path": "/v1.0/pdf/upload-binary",
+                      "status": 400,
+                      "error": "Invalid Parameter",
+                      "message": "Invalid parameter value provided for 'dataBufferFlux'."
+                    }
+                  }
+                },
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "415": {
+            "description": "Unsupported Media Type \u2014 File extension not supported",
+            "content": {
+              "application/json": {
+                "examples": {
+                  "UnsupportedFileType": {
+                    "summary": "Unsupported file type",
+                    "value": {
+                      "timestamp": "2026-07-27T10:48:15.449Z",
+                      "path": "/v1.0/pdf/upload-binary",
+                      "status": 415,
+                      "error": "Unsupported File Type",
+                      "message": "The provided file type is not supported. Refer to the documentation for valid file types."
+                    }
+                  }
+                },
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "operationId": "uploadResourceBinary"
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "BinaryResourceUploadResponse": {
+        "type": "object",
+        "required": [
+          "fileName",
+          "fileId"
+        ],
+        "properties": {
+          "fileName": {
+            "type": "string",
+            "description": "The name of the uploaded file."
+          },
+          "fileId": {
+            "type": "string",
+            "description": "The unique identifier assigned to the uploaded file."
+          }
+        },
+        "description": "Binary resource upload response containing file metadata."
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests.",
+        "required": [
+          "message"
+        ],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}