@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/pdf/delete-pdf-page.yaml

@@ -0,0 +1,193 @@
+openapi: 3.1.1
+info:
+  title: PDF Remove Pages API - Delete PDF Pages and Clean Up Documents Instantly
+  version: 1.0.0
+  description: Remove specific pages from a PDF file. Specify page numbers to delete. Returns a task ID for tracking the deletion progress.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: PDF Remove Pages API Server
+paths:
+  /pdf/remove-pages:
+    post:
+      tags:
+        - PDF Operations APIs
+      summary: Delete specific pages from a PDF
+      description: This API removes a selection or range of pages from a PDF file.
+      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 identifier 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 name for the output PDF file after pages have been removed. If not provided, a default name will be assigned.
+        - name: pages
+          in: query
+          required: true
+          schema:
+            type: string
+          description: 'Specifies which pages to remove from the PDF. Accepts individual page numbers (e.g., ''1,7'') and/or ascending page ranges (e.g., ''3-5''). Use commas to separate entries and hyphens for ranges. Reverse ranges (e.g., ''5-3'') are not allowed. Alternatively, you may provide only one of the following keywords: ''even'' (removes all even-numbered pages), ''odd'' (removes all odd-numbered pages), or ''last'' (removes only the last page). The keyword ''all'' is not supported for this operation. Examples: ''1,3-5'', ''even''. Mixing special keywords with specific pages/ranges is not allowed. Malformed values or page numbers exceeding the document''s page count are not rejected on this call — the resulting task fails asynchronously (check task status).'
+        - 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’s 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 remove pages from. 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: Remove task created successfully. Malformed or out-of-range page specifications are not rejected synchronously — 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: 04a06cd5-158d-4191-a45b-6f58249c599d
+                    inputIds:
+                      - 7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f
+        '400':
+          description: Bad Request — Missing/invalid parameters or file ID
+          content:
+            application/json:
+              examples:
+                MissingPages:
+                  summary: Missing required pages parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/pdf/remove-pages
+                    status: 400
+                    timestamp: '2026-07-27T10:52:11.692Z'
+                InvalidID:
+                  summary: file_id is malformed or does not exist
+                  value:
+                    timestamp: '2026-07-27T10:52:14.049Z'
+                    path: /v1.0/pdf/remove-pages
+                    status: 400
+                    error: Invalid File ID Provided
+                    message: Please provide a valid file ID
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: Unsupported Media Type — File type not supported
+          content:
+            application/json:
+              examples:
+                InvalidPDF:
+                  summary: Uploaded file is not a supported type
+                  value:
+                    timestamp: '2026-07-27T10:52:14.649Z'
+                    path: /v1.0/pdf/remove-pages
+                    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: deletePdfPage
+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/dist/specs/pdf/linearize-pdf.yaml

@@ -0,0 +1,187 @@
+openapi: 3.1.1
+info:
+  title: PDF Linearize API - Optimize PDFs for Fast Web Viewing
+  version: 1.0.0
+  description: Linearize (web-optimize) a PDF file for faster viewing in web browsers. Optimized PDFs load page-by-page without downloading the entire file.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Linearize PDF API Server
+paths:
+  /pdf/linearize:
+    post:
+      tags:
+        - PDF Operations APIs
+      summary: Linearize a PDF
+      description: API endpoint that linearizes any given PDF, restructuring it for faster loading and page-by-page viewing in web browsers.
+      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 name for the output PDF file after pages have been extracted. If not provided, a default name will be assigned.
+        - 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’s 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 linearize. 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: Linearize task created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PDFResponse'
+              examples:
+                success:
+                  summary: Task created
+                  value:
+                    taskId: 8750f9bb-4cb9-45fd-80a6-e1adf6556618
+                    inputIds:
+                      - 5f214118-f848-41f8-809d-8c6058b4b74a
+        '400':
+          description: Bad Request — Missing/invalid file or file ID
+          content:
+            application/json:
+              examples:
+                MissingFileOrID:
+                  summary: Neither a file nor a file ID was provided
+                  value:
+                    timestamp: '2026-07-27T10:55:07.695Z'
+                    path: /v1.0/pdf/linearize
+                    status: 400
+                    message: Please provide either a file or a file ID.
+                    error: Missing File or ID
+                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/linearize
+                    status: 400
+                    timestamp: '2026-07-27T10:55:08.238Z'
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: Unsupported Media Type — File type not supported
+          content:
+            application/json:
+              examples:
+                UnsupportedFileType:
+                  summary: Uploaded file is not a supported type
+                  value:
+                    timestamp: '2026-07-27T10:55:08.869Z'
+                    path: /v1.0/pdf/linearize
+                    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: linearizePdf
+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/dist/specs/pdf/merge-pdf.yaml

@@ -0,0 +1,193 @@
+openapi: 3.1.1
+info:
+  title: Merge PDF API - Instantly Combine PDFs at Scale
+  version: 1.0.1
+  description: Merge multiple PDF files into a single PDF document in the order they are provided. Accepts input files up to 1GB in size via file upload or existing file IDs. Returns a task ID for tracking the merge progress.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: PDF Merge API Server
+paths:
+  /pdf/merge:
+    post:
+      tags:
+        - PDF Operations APIs
+      summary: Combine multiple PDF files into one
+      description: This API merges multiple PDF files into a single PDF, in the order they are provided
+      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: array
+            items:
+              type: string
+              default: ''
+            default: []
+          description: An array of unique file IDs referencing PDF files previously uploaded to the API Freaks server. Use this parameter to merge existing files without re-uploading them. Provide multiple IDs to merge files in the specified order.
+        - 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: Specifies the desired name for the resulting merged PDF file. If not provided, a default name will be assigned.
+        - 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’s 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(s) to merge. Alternatively, reference already-uploaded files via the file_id query parameter instead of uploading here.
+        required: false
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/PdfMergeUploadRequest'
+      responses:
+        '200':
+          description: Merge task created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PDFResponse'
+              examples:
+                success:
+                  summary: Task created
+                  value:
+                    taskId: 04a06cd5-158d-4191-a45b-6f58249c599d
+                    inputIds:
+                      - 7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              examples:
+                InvalidID:
+                  summary: Invalid file ID provided
+                  value:
+                    error: Invalid File ID Provided
+                    message: Please provide a valid file ID
+                    path: /v1.0/pdf/merge
+                    status: 400
+                    timestamp: '2026-07-27T10:49:41.973Z'
+                MissingUploadOrId:
+                  summary: Neither a file nor a file ID was provided
+                  value:
+                    timestamp: '2026-07-27T10:49:41.432Z'
+                    path: /v1.0/pdf/merge-pdf
+                    status: 400
+                    error: Missing File or ID
+                    message: Please provide either a file or a file ID.
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '415':
+          description: Unsupported Media Type — File type not supported
+          content:
+            application/json:
+              examples:
+                UnsupportedFileType:
+                  summary: Unsupported file type
+                  value:
+                    timestamp: '2026-07-27T10:49:42.554Z'
+                    path: /v1.0/pdf/merge-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: mergePdf
+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
+      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.
+      description: Response containing the task ID and input file IDs for a PDF processing task.
+    PdfMergeUploadRequest:
+      type: object
+      description: Multipart form-data request body containing multiple PDF files to merge.
+      required: []
+      properties:
+        file:
+          type: array
+          items:
+            type: string
+            format: binary
+          description: One or more raw PDF file byte streams, each sent as a separate multipart/form-data field named 'file'. Omit this field entirely and pass one or more file_id query parameters instead to merge already-uploaded files.
+    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: []