@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/pdf/pdf-extract-pages.yaml

@@ -0,0 +1,199 @@
+openapi: 3.1.1
+info:
+  title: PDF Extract Pages API Reference
+  version: 1.0.0
+  description: Extract specific pages from a PDF file. Specify page ranges or individual page numbers. Returns a task ID for tracking the extraction progress.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: PDF Extract Pages API Server
+paths:
+  /pdf/extract-pages:
+    post:
+      tags:
+        - PDF Operations APIs
+      summary: Extract pages from a PDF
+      description: This API extracts specific pages or page ranges from a PDF file and returns them as a new PDF.
+      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: pages
+          in: query
+          required: true
+          schema:
+            type: string
+          description: 'Specifies which pages to extract from the PDF. You can provide individual page numbers (e.g., ''2'') and/or page ranges in any order, including descending (e.g., ''9-5'', ''16-last''). Use commas to separate entries and hyphens for ranges. You may alternatively pass only one of the special keywords: ''even'' (extracts all even-numbered pages), ''odd'' (extracts all odd-numbered pages), ''last'' (extracts only the last page), or ''all'' (extracts all pages into individual files). Examples: ''2,6-3'', ''even'', ''all''. 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: separated
+          in: query
+          required: false
+          schema:
+            type: boolean
+          description: If set to `true`, each of the specified pages will be extracted and returned as a separate PDF file.
+        - 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 extract 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: Extract 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: dabcbcf5-d4ba-4143-bc34-3a8db6c8476e
+                    inputIds:
+                      - 01a77122-c457-475d-a6f2-f88cd4ad8924
+        '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/extract-pages
+                    status: 400
+                    timestamp: '2026-07-27T10:53:18.573Z'
+                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/extract-pages
+                    status: 400
+                    timestamp: '2026-07-27T10:53:19.182Z'
+              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:53:19.733Z'
+                    path: /v1.0/pdf/extract-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: extractPdfPages
+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/pdf-file-status.yaml

@@ -0,0 +1,148 @@
+openapi: 3.1.1
+info:
+  title: PDF File Status API Reference
+  version: 1.0.0
+  description: Check the status of a PDF file using its unique file ID. Returns file metadata including name, type, creation time, and scheduled deletion time. Use this endpoint to verify file availability after upload or before processing.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: PDF File Status API Server
+paths:
+  /pdf/file-status:
+    get:
+      tags:
+        - Task Status and File Info APIs
+      summary: Check file status
+      description: This API checks the status of a PDF file using its unique file ID, providing information about its creation and potential deletion time.
+      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
+          description: The unique ID of the file whose status is requested.
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FileStatusResponse'
+              examples:
+                success:
+                  summary: File found
+                  value:
+                    fileId: b7ece7d4-1141-4143-98cb-7b4b818d6d82
+                    fileName: test.pdf
+                    fileType: pdf
+                    fileCreationTime: '2026-07-27T10:46:36'
+                    fileDeletionTime: '2026-08-26'
+        '400':
+          description: Bad Request — Missing required file_id parameter
+          content:
+            application/json:
+              examples:
+                missingFileId:
+                  summary: Missing file_id parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/pdf/file-status
+                    status: 400
+                    timestamp: '2026-07-27T10:46:38.333Z'
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: File ID Not Found
+          content:
+            application/json:
+              examples:
+                error:
+                  summary: File ID not found
+                  value:
+                    timestamp: '2026-07-27T10:46:37.828Z'
+                    path: /v1.0/pdf/file-status
+                    status: 404
+                    error: File ID Not Found
+                    message: Please provide a valid file ID.
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      operationId: getFileStatus
+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:
+    FileStatusResponse:
+      type: object
+      required:
+        - fileId
+        - fileName
+        - fileType
+        - fileCreationTime
+        - fileDeletionTime
+      properties:
+        fileId:
+          type: string
+          description: The unique identifier of the file.
+        fileName:
+          type: string
+          description: The name of the file.
+        fileType:
+          type: string
+          description: The type of the file (e.g., 'pdf').
+        fileCreationTime:
+          type: string
+          format: date-time
+          description: The timestamp when the file was created.
+        fileDeletionTime:
+          type: string
+          format: date
+          description: Date on which the file is scheduled to be deleted, in UTC.
+      description: File status response containing metadata about the PDF 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/pdf-file.yaml

@@ -0,0 +1,136 @@
+openapi: 3.1.1
+info:
+  title: PDF Delete File API Reference
+  version: 1.0.0
+  description: Delete a PDF file from the server using its unique file ID. Once deleted, the file ID cannot be used in other API calls. Returns a success indicator and confirmation message.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: PDF Delete File API Server
+paths:
+  /pdf/file:
+    delete:
+      tags:
+        - Task Status and File Info APIs
+      summary: Delete a PDF file
+      description: This API deletes a PDF file using its unique file 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: file_id
+          in: query
+          description: The unique ID of the file to be deleted.
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DeleteFileResponse'
+              examples:
+                success:
+                  summary: File deleted
+                  value:
+                    fileId: abc123
+                    success: true
+                    message: File deleted successfully.
+        '400':
+          description: Bad Request — Missing required file_id parameter
+          content:
+            application/json:
+              examples:
+                missingFileId:
+                  summary: Missing file_id parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/pdf/file
+                    status: 400
+                    timestamp: '2026-07-27T10:45:56.656Z'
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: File ID Not Found
+          content:
+            application/json:
+              examples:
+                error:
+                  summary: File ID not found or already deleted
+                  value:
+                    timestamp: '2026-07-27T10:45:55.737Z'
+                    path: /v1.0/pdf/file
+                    status: 404
+                    error: File ID Not Found
+                    message: Please provide a valid file ID.
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      operationId: deleteFile
+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:
+    DeleteFileResponse:
+      type: object
+      required:
+        - fileId
+        - success
+        - message
+      properties:
+        fileId:
+          type: string
+          description: The unique identifier of the file.
+        success:
+          type: boolean
+          description: Indicates whether the file deletion request was successful.
+        message:
+          type: string
+          description: A message indicating the result of the file deletion request.
+      description: File deletion response containing the result of the delete operation.
+    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/pdf-files.yaml

@@ -0,0 +1,85 @@
+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/dist/specs/pdf/pdf-resource-download.yaml

@@ -0,0 +1,117 @@
+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: []