@apifreaks/openapi-specs 0.1.0

package/specs/pdf/pdf-split-pages.json

@@ -0,0 +1,281 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "PDF Split API Reference",
+    "version": "1.0.0",
+    "description": "Split a PDF file into individual pages or groups of pages. Returns a task ID for tracking the split progress.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "PDF Split API Server"
+    }
+  ],
+  "paths": {
+    "/pdf/split": {
+      "post": {
+        "tags": [
+          "PDF Operations APIs"
+        ],
+        "summary": "Split a PDF into smaller files",
+        "description": "This API splits a PDF into multiple parts based on specified page numbers or ranges.",
+        "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_id",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "The unique ID of a PDF file already uploaded to the API Freaks server. Use this as an alternative to uploading a new file directly."
+          },
+          {
+            "name": "destroy",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "boolean"
+            },
+            "description": "If set to `true`, the input file(s) will be permanently deleted from the server immediately after the output PDF is generated."
+          },
+          {
+            "name": "output",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "The desired base name for the output PDF files after splitting. If not provided, a default naming convention will be used."
+          },
+          {
+            "name": "pages",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "default": ""
+              },
+              "default": []
+            },
+            "description": "Defines the page numbers or ranges where the PDF should be split. Provide individual pages and/or ranges in any order (for example: \"1-4,9-5,16-last\"). Separate entries with commas and use hyphens for ranges.\n\nSpecial keywords (use alone):\n\n\u2022 `even` \u2014 split at every even-numbered page\n\n\u2022 `odd` \u2014 split at every odd-numbered page\n\n\u2022 `all` \u2014 split the PDF into single-page files\n\nThe keyword `last` can be used anywhere in the string, in combination with page numbers or ranges (for example: \"5-last\", \"last-2\", \"1,last,9\").\n\nExamples:\n- \"1,4-2,last\"\n- \"odd\"\n- \"all\"\n- \"last,2-5\"\n\nInvalid example: \"1,odd\" (mixing a keyword other than \"last\" with specific pages/ranges is not allowed). You can pass multiple pages entries to produce multiple output files."
+          },
+          {
+            "name": "webhook_url",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "The URL to which the webhook notification will be sent after the task is completed."
+          },
+          {
+            "name": "webhook_failure_notification",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "boolean"
+            },
+            "description": "If true, a notification will also be sent by email in case the webhook request fails all the retries.  The email notification will be sent to the requesting user or their organization\u2019s admin if part of one."
+          },
+          {
+            "name": "X-Webhook-Authorization",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Optional custom header for webhook requests. Format: `Key:Value` (e.g., `Authorization:Bearer token123`). This will be sent as an HTTP header in the webhook call."
+          }
+        ],
+        "requestBody": {
+          "description": "Multipart form-data body carrying the PDF file to split. Alternatively, reference an already-uploaded file via the file_id query parameter instead of uploading here.",
+          "required": false,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/PdfFileUploadRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Split task created successfully. Malformed or out-of-range page specifications are not rejected synchronously \u2014 the task is created, then fails asynchronously; poll the task status endpoint and check for status \"failed\" with an error/message pair.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PDFResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Task created",
+                    "value": {
+                      "taskId": "a533a95c-b3fb-49f0-abb1-bef2f3e805ef",
+                      "inputIds": [
+                        "62f910b6-69ce-4cbc-8285-eee5f16467be"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request \u2014 Invalid file ID",
+            "content": {
+              "application/json": {
+                "examples": {
+                  "InvalidID": {
+                    "summary": "file_id is malformed or does not exist",
+                    "value": {
+                      "error": "Invalid File ID Provided",
+                      "message": "Please provide a valid file ID",
+                      "path": "/v1.0/pdf/split",
+                      "status": 400,
+                      "timestamp": "2026-07-27T10:54:00.793Z"
+                    }
+                  }
+                },
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "415": {
+            "description": "Unsupported Media Type \u2014 File type not supported",
+            "content": {
+              "application/json": {
+                "examples": {
+                  "UnsupportedFileType": {
+                    "summary": "Uploaded file is not a supported type",
+                    "value": {
+                      "timestamp": "2026-07-27T10:54:01.347Z",
+                      "path": "/v1.0/pdf/split-pdf",
+                      "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": "splitPdf"
+      }
+    }
+  },
+  "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": {
+      "PDFResponse": {
+        "type": "object",
+        "description": "Response containing the task ID and input file IDs for a PDF processing task.",
+        "required": [
+          "taskId"
+        ],
+        "properties": {
+          "taskId": {
+            "type": "string",
+            "description": "Task ID of the requested task, used to check the task status."
+          },
+          "inputIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "File IDs for the input files provided for the task. Not returned when destroy parameter is true."
+          }
+        }
+      },
+      "PdfFileUploadRequest": {
+        "type": "object",
+        "description": "Multipart form-data request body containing the PDF file to process.",
+        "required": [],
+        "properties": {
+          "file": {
+            "type": "string",
+            "format": "binary",
+            "description": "Raw PDF file bytes sent as a multipart/form-data field named 'file'. Omit this field entirely and pass file_id in the query string instead to use an already-uploaded file."
+          }
+        }
+      },
+      "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-task-status.json

@@ -0,0 +1,252 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "PDF Task Status API Reference",
+    "version": "1.0.0",
+    "description": "Check the status of a previously initiated PDF processing task using its unique task ID. Returns task status, creation and expiry timestamps, output file URLs and IDs, and input file IDs. Supports status values: queued, processing, completed, failed.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "PDF Task Status API Server"
+    }
+  ],
+  "paths": {
+    "/pdf/task-status": {
+      "get": {
+        "tags": ["Task Status and File Info APIs"],
+        "summary": "Check PDF task status",
+        "description": "This API checks the status of a previously initiated PDF processing task using its unique task ID.",
+        "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": "task_id",
+            "in": "query",
+            "description": "The unique ID of the PDF processing task for which the status is requested.",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Task status retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TaskStatusResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Task completed",
+                    "value": {
+                      "taskId": "74004a68-ec05-4681-8d10-698304206065",
+                      "status": "completed",
+                      "createdAt": "2026-07-27 10:48:51",
+                      "outputUrls": [
+                        "https://api.apifreaks.com/v1.0/pdf/resource/download?resource_id=21e3bb30-f98e-47ca-9d52-b221857d1f48"
+                      ],
+                      "outputIds": ["21e3bb30-f98e-47ca-9d52-b221857d1f48"],
+                      "inputIds": [
+                        "0deab2f6-927c-451e-81e2-e8565206690e",
+                        "5b6a4836-8c4c-4379-8b3c-0867be35db71"
+                      ],
+                      "expiresAt": "2026-08-03 10:48:51"
+                    }
+                  },
+                  "failed": {
+                    "summary": "Task failed (e.g. invalid page range/format caught during processing)",
+                    "value": {
+                      "taskId": "9d8d803b-e23a-4431-901b-98b1f337355c",
+                      "status": "failed",
+                      "createdAt": "2026-07-27 10:52:12",
+                      "inputIds": ["63ea4110-b007-475b-9211-2fa7138b8ba1"],
+                      "error": "Invalid Page Range",
+                      "message": "One or more specified page numbers exceed the total number of pages in the PDF document.",
+                      "expiresAt": "2026-08-03 10:52:12"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Missing required task_id parameter",
+            "content": {
+              "application/json": {
+                "examples": {
+                  "missingTaskId": {
+                    "summary": "Missing task_id parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/pdf/task-status",
+                      "status": 400,
+                      "timestamp": "2026-07-27T10:49:06.412Z"
+                    }
+                  }
+                },
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Task ID Not Found",
+            "content": {
+              "application/json": {
+                "examples": {
+                  "error": {
+                    "summary": "Task ID not found",
+                    "value": {
+                      "timestamp": "2026-07-27T10:49:05.829Z",
+                      "path": "/v1.0/pdf/task-status",
+                      "status": 404,
+                      "error": "Task ID Not Found",
+                      "message": "Please provide a valid task ID."
+                    }
+                  }
+                },
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        },
+        "operationId": "getTaskStatus"
+      }
+    }
+  },
+  "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": {
+      "TaskStatusResponse": {
+        "type": "object",
+        "required": ["taskId", "status", "createdAt", "inputIds", "expiresAt"],
+        "properties": {
+          "taskId": {
+            "type": "string",
+            "description": "The unique identifier of the PDF processing task."
+          },
+          "status": {
+            "type": "string",
+            "description": "The current status of the task (e.g., 'queued', 'processing', 'completed', 'failed')."
+          },
+          "createdAt": {
+            "type": "string",
+            "description": "The timestamp when the task status was created, formatted as 'yyyy-MM-dd HH:mm:ss'."
+          },
+          "zipFileId": {
+            "type": "string",
+            "description": "The unique identifier for the ZIP file. This is present only when the task status is 'COMPLETED'."
+          },
+          "outputUrls": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "A list of URLs for each individual output file. This is present only when the task is 'COMPLETED'."
+          },
+          "outputIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "A list of unique IDs for the output files. This is present only when the task is 'COMPLETED'."
+          },
+          "inputIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "A list of unique IDs for the input files submitted with the task. If the task was initiated with the `destroy` parameter set to `true`, `inputIds` will not be generated."
+          },
+          "error": {
+            "type": "string",
+            "description": "The error code for the PDF Task. This is included only if the task fails."
+          },
+          "message": {
+            "type": "string",
+            "description": "A descriptive message indicating the reason for task failure. This is included only if the task fails."
+          },
+          "expiresAt": {
+            "type": "string",
+            "description": "The timestamp when the task status will expire and be removed from the system, formatted as 'yyyy-MM-dd HH:mm:ss'."
+          },
+          "zipFileUrl": {
+            "type": "string",
+            "description": "The URL to download all output files as a single ZIP archive. Present only when the task status is completed."
+          }
+        },
+        "description": "Task status response containing the current state of a PDF processing task."
+      },
+      "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": []
+    }
+  ]
+}