@apifreaks/openapi-specs 0.1.2 → 0.3.0

package/dist/specs/pdf/pdf-generator.yaml

@@ -0,0 +1,348 @@
+openapi: 3.1.1
+info:
+  title: PDF Generator API - Create PDFs from Templates
+  version: 1.0.0
+  description: Generate PDFs from templates you design once in the APIFreaks PDF Template Builder. Send JSON in the request body or provide a data_url, and the API renders your template into a hosted PDF document. Authentication is done with your APIFreaks API key passed in the X-apikey header.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: PDF Generator API Server
+paths:
+  /pdf/template/generate:
+    post:
+      tags:
+        - PDF Template APIs
+      summary: Generate a PDF from a template
+      description: Renders the template identified by template_id with the JSON data supplied in the request body (or fetched from data_url). Returns a hosted URL for the generated PDF. Provide either a request body or a data_url; one of the two is required. The keys of the data object are the fields you bound when you designed the template in the APIFreaks PDF Template Builder, so the exact shape is up to you. Pin the version parameter to a specific template version (e.g. version=v2) so later design changes never touch what is already live; omit it to use the latest version.
+      parameters:
+        - name: template_id
+          in: query
+          required: true
+          schema:
+            type: string
+          description: The template to render, from the APIFreaks PDF Template Builder. Copy it from your dashboard when you save the template.
+        - name: version
+          in: query
+          required: false
+          schema:
+            type: string
+            pattern: ^v
+          description: Template version to render, e.g. v2. Must start with v. Omit this parameter entirely to use the latest version; the literal value 'latest' is not accepted by the API.
+        - name: data_url
+          in: query
+          required: false
+          schema:
+            type: string
+            format: uri
+          description: A URL the API fetches your JSON data from, instead of the request body. Provide this when you are not sending a request body.
+      requestBody:
+        description: The template's data as a JSON object. The keys are the fields you bound when you designed the template, so the exact shape is up to you. Provide the body when you are not passing a data_url; one of the two is required.
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+              description: Free-form JSON object whose keys map to the fields bound in the template.
+            examples:
+              resumeTemplate:
+                summary: Resume template data
+                value:
+                  candidate_name: Ava Thompson
+                  candidate_title: Senior Operations Analyst
+                  email: ava.thompson@example.com
+                  phone: +1 (555) 381-2048
+                  city: Austin, TX
+                  portfolio_url: portfolio.example.com
+                  profile_summary: Analytical operations professional with 8+ years of experience improving reporting pipelines, streamlining process documentation, and coordinating cross-functional delivery for distributed teams across multiple time zones.
+                  company_name: Northwind Logistics
+                  job_title: Operations Analyst
+                  employment_period: 2021 - Present
+                  job_achievement_1: Led weekly KPI reporting for finance, fulfillment, and customer success stakeholders across three business units.
+                  job_achievement_2: Reduced manual reconciliation work by 35% through workflow redesign and documentation automation.
+                  job_achievement_3: Spearheaded a cross-team initiative that improved on-time delivery metrics by 18% within six months.
+                  skills:
+                    - skill: Process Improvement
+                      level: Advanced
+                      years: '7'
+                    - skill: Stakeholder Reporting
+                      level: Expert
+                      years: '8'
+                    - skill: Cross-functional Coordination
+                      level: Advanced
+                      years: '5'
+                    - skill: Workflow Documentation
+                      level: Advanced
+                      years: '6'
+                  degree: B.S. in Information Systems
+                  institution: University of Texas
+                  graduation_year: '2018'
+                  certification_1: Certified Business Analysis Professional (CBAP)
+                  certification_2: Six Sigma Green Belt
+                  languages: English (Native), Spanish (Professional)
+              businessReport:
+                summary: Business report template data
+                value:
+                  report_title: Quarterly Business Report
+                  report_period: Q4 2024
+                  prepared_by: Marketing Team
+                  revenue: 125000
+                  growth_rate: 15
+                  customer_count: 520
+                  monthly_comparison:
+                    - metric: Revenue
+                      previous: $108,000
+                      current: $125,000
+                      change: +15.7%
+                    - metric: Active Customers
+                      previous: '480'
+                      current: '520'
+                      change: +8.3%
+      responses:
+        '200':
+          description: PDF generated successfully. The response contains the hosted URL of the rendered PDF along with its creation and expiration times.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TemplateGenerationResponse'
+              examples:
+                success:
+                  summary: Generated PDF
+                  value:
+                    template_id: 73691bce-1c58-4370-acc6-64b2dd14f81c
+                    pdf_url: https://s3.eu-central-2.wasabisys.com/w.storage.apifreaks.com/pdf_templates/73691bce-1c58-4370-acc6-64b2dd14f81c/Candidate%20Resume_20260810141214723405.pdf
+                    created_at: '2026-08-10T14:12:17.673Z'
+                    expiration_time: '2026-11-10T14:12:17.673Z'
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
+        '400':
+          description: Bad Request — Missing or malformed parameters, missing data, or an unreachable data_url.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                MissingTemplateId:
+                  summary: template_id is missing
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/pdf/template/generate
+                    status: 400
+                    timestamp: '2026-08-10T14:13:13.195Z'
+                InvalidVersion:
+                  summary: version does not start with v
+                  value:
+                    timestamp: '2026-08-10T14:13:13.689Z'
+                    path: /v1.0/generate-pdf
+                    status: 400
+                    error: Invalid Template Version
+                    message: Please provide a valid template version starting with 'v'.
+                NoData:
+                  summary: No data supplied to fill the template
+                  value:
+                    timestamp: '2026-08-10T14:13:14.172Z'
+                    path: /v1.0/generate-pdf
+                    status: 400
+                    error: Template Data Not Provided
+                    message: No data provided for the template. Please provide valid data to generate pdf.
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
+        '401':
+          description: Unauthorized — The API key is missing or invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                InvalidApiKey:
+                  summary: Provided API key is invalid
+                  value:
+                    error: API Access Exception
+                    message: 'Provided API key is invalid. [For Technical Support: support@apifreaks.com]'
+                    path: /v1.0/pdf/template/generate
+                    status: 401
+                    timestamp: '2026-08-10T14:13:14.996Z'
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
+        '403':
+          description: Forbidden — The account does not have access to this template.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                AccessDenied:
+                  summary: No access to the template
+                  value:
+                    timestamp: '2026-08-10T14:13:15.000Z'
+                    path: /v1.0/generate-pdf
+                    status: 403
+                    error: Template Access Denied
+                    message: Your account does not have access to this template.
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
+        '404':
+          description: Not Found — No template matches the template_id, or the requested version does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                TemplateNotFound:
+                  summary: No template matches the template_id
+                  value:
+                    timestamp: '2026-08-10T14:13:14.677Z'
+                    path: /v1.0/generate-pdf
+                    status: 404
+                    error: Template Not Found
+                    message: Please provide a valid template ID.
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
+        '415':
+          description: Unsupported Media Type — The request Content-Type is not supported for this endpoint.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                UnsupportedMediaType:
+                  summary: Content-Type is not supported
+                  value:
+                    timestamp: '2026-08-10T14:13:15.500Z'
+                    path: /v1.0/generate-pdf
+                    status: 415
+                    error: Unsupported Media Type
+                    message: The request Content-Type is not supported for this endpoint.
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
+        '422':
+          description: Unprocessable Entity — The request contains invalid or missing data.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                InvalidData:
+                  summary: Invalid or missing data
+                  value:
+                    timestamp: '2026-08-10T14:13:16.100Z'
+                    path: /v1.0/generate-pdf
+                    status: 422
+                    error: Invalid Template Data
+                    message: The request contains invalid or missing data.
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
+        '500':
+          description: Internal Server Error — An unexpected error occurred, or the PDF could not be generated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                GenerationFailed:
+                  summary: PDF could not be generated
+                  value:
+                    timestamp: '2026-08-10T14:13:16.700Z'
+                    path: /v1.0/generate-pdf
+                    status: 500
+                    error: PDF Generation Failed
+                    message: The PDF could not be generated. Try the request again.
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
+        '504':
+          description: Gateway Timeout — The request went past the 100 second processing limit.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                ProcessingLimit:
+                  summary: Request exceeded the 100 second processing limit
+                  value:
+                    timestamp: '2026-08-10T14:13:17.300Z'
+                    path: /v1.0/generate-pdf
+                    status: 504
+                    error: Processing Timeout
+                    message: The request went past the 100 second processing limit. Reduce the input size or retry.
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
+      operationId: generatePdfFromTemplate
+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:
+    TemplateGenerationResponse:
+      type: object
+      description: Result of a PDF generation request, containing the hosted URL of the generated PDF.
+      required:
+        - template_id
+        - pdf_url
+        - created_at
+        - expiration_time
+      properties:
+        template_id:
+          type: string
+          description: The template that was rendered.
+        pdf_url:
+          type: string
+          description: Hosted URL of the generated PDF.
+        created_at:
+          type: string
+          format: date-time
+          description: When the PDF was generated (ISO 8601).
+        expiration_time:
+          type: string
+          format: date-time
+          description: When the hosted PDF expires (ISO 8601).
+    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).
+  headers:
+    X-AF-Credits-Cost:
+      description: Specifies the number of credits consumed by the current request.
+      schema:
+        type: integer
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []

package/dist/specs/pdf/pdf-resource-download.yaml

@@ -46,6 +46,9 @@ paths:
               schema:
                 type: string
                 format: binary
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '400':
           description: Bad Request — Missing required resource_id parameter
           content:
@@ -61,6 +64,9 @@ paths:
                     timestamp: '2026-07-27T10:47:12.356Z'
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '404':
           description: Resource ID Not Found
           content:
@@ -76,6 +82,9 @@ paths:
                     message: Please provide a valid resource ID.
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
       operationId: downloadResource
 components:
   securitySchemes:
@@ -112,6 +121,11 @@ components:
           type: string
           format: date-time
           description: Timestamp when the error occurred (ISO 8601).
+  headers:
+    X-AF-Credits-Cost:
+      description: Specifies the number of credits consumed by the current request.
+      schema:
+        type: integer
 security:
   - ApiKeyAuthHeader: []
   - ApiKeyAuthQuery: []

package/dist/specs/pdf/pdf-resource-upload-binary.yaml

@@ -60,6 +60,9 @@ paths:
                   value:
                     fileName: binarytest.pdf
                     fileId: b0fbf78c-8fe2-49b6-ad3d-63efb4ac8e58
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '400':
           description: Bad Request — Missing file_name or empty body
           content:
@@ -83,6 +86,9 @@ paths:
                     message: Invalid parameter value provided for 'dataBufferFlux'.
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '415':
           description: Unsupported Media Type — File extension not supported
           content:
@@ -98,6 +104,9 @@ paths:
                     message: The provided file type is not supported. Refer to the documentation for valid file types.
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
       operationId: uploadResourceBinary
 components:
   securitySchemes:
@@ -147,6 +156,11 @@ components:
           type: string
           format: date-time
           description: Timestamp when the error occurred (ISO 8601).
+  headers:
+    X-AF-Credits-Cost:
+      description: Specifies the number of credits consumed by the current request.
+      schema:
+        type: integer
 security:
   - ApiKeyAuthHeader: []
   - ApiKeyAuthQuery: []

package/dist/specs/pdf/pdf-resource-upload.yaml

@@ -63,6 +63,9 @@ paths:
                         fileId: 9922d104-25a0-432c-8c26-2be2ba14798a
                       - fileName: test.pdf
                         fileId: 8a6b3332-6fe0-42b0-a808-df7a36926a79
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '400':
           description: Bad Request — Missing or invalid parameters
           content:
@@ -78,6 +81,9 @@ paths:
                     status: 400
                     error: Missing or Invalid Parameters
                     message: One or more required parameters are missing or incorrect.
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '415':
           description: Unsupported Media Type — File type not supported
           content:
@@ -93,6 +99,9 @@ paths:
                     status: 415
                     error: Unsupported File Type
                     message: The provided file type is not supported. Refer to the documentation for valid file types.
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
 components:
   securitySchemes:
     ApiKeyAuthHeader:
@@ -158,6 +167,11 @@ components:
           type: string
           format: date-time
           description: Timestamp when the error occurred (ISO 8601).
+  headers:
+    X-AF-Credits-Cost:
+      description: Specifies the number of credits consumed by the current request.
+      schema:
+        type: integer
 security:
   - ApiKeyAuthHeader: []
   - ApiKeyAuthQuery: []

package/dist/specs/pdf/pdf-restrict.yaml

@@ -120,6 +120,9 @@ paths:
                     taskId: 42839406-7e1b-4f64-96bb-d94bb054e8d3
                     inputIds:
                       - 2c682ade-eccc-4ab5-9c06-d16e415cbecb
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '400':
           description: Bad Request — Missing/invalid parameters, file ID, or password
           content:
@@ -167,6 +170,9 @@ paths:
                     message: Please provide valid PDF restrictions. Refer to the documentation for valid PDF restrictions.
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '415':
           description: Unsupported Media Type — File type not supported
           content:
@@ -182,6 +188,9 @@ paths:
                     status: 415
                     error: Unsupported File Type
                     message: The provided file type is not supported. Refer to the documentation for valid file types.
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
       operationId: restrictPdf
 components:
   securitySchemes:
@@ -241,6 +250,11 @@ components:
           type: string
           format: date-time
           description: Timestamp when the error occurred (ISO 8601).
+  headers:
+    X-AF-Credits-Cost:
+      description: Specifies the number of credits consumed by the current request.
+      schema:
+        type: integer
 security:
   - ApiKeyAuthHeader: []
   - ApiKeyAuthQuery: []

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

@@ -114,6 +114,9 @@ paths:
                     taskId: a533a95c-b3fb-49f0-abb1-bef2f3e805ef
                     inputIds:
                       - 62f910b6-69ce-4cbc-8285-eee5f16467be
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '400':
           description: Bad Request — Invalid file ID
           content:
@@ -129,6 +132,9 @@ paths:
                     timestamp: '2026-07-27T10:54:00.793Z'
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '415':
           description: Unsupported Media Type — File type not supported
           content:
@@ -144,6 +150,9 @@ paths:
                     message: The provided file type is not supported. Refer to the documentation for valid file types.
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
       operationId: splitPdf
 components:
   securitySchemes:
@@ -203,6 +212,11 @@ components:
           type: string
           format: date-time
           description: Timestamp when the error occurred (ISO 8601).
+  headers:
+    X-AF-Credits-Cost:
+      description: Specifies the number of credits consumed by the current request.
+      schema:
+        type: integer
 security:
   - ApiKeyAuthHeader: []
   - ApiKeyAuthQuery: []

package/dist/specs/pdf/pdf-task-status.yaml

@@ -67,6 +67,9 @@ paths:
                     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'
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '400':
           description: Bad Request — Missing required task_id parameter
           content:
@@ -82,6 +85,9 @@ paths:
                     timestamp: '2026-07-27T10:49:06.412Z'
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
         '404':
           description: Task ID Not Found
           content:
@@ -97,6 +103,9 @@ paths:
                     message: Please provide a valid task ID.
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+          headers:
+            X-AF-Credits-Cost:
+              $ref: '#/components/headers/X-AF-Credits-Cost'
       operationId: getTaskStatus
 components:
   securitySchemes:
@@ -182,6 +191,11 @@ components:
           type: string
           format: date-time
           description: Timestamp when the error occurred (ISO 8601).
+  headers:
+    X-AF-Credits-Cost:
+      description: Specifies the number of credits consumed by the current request.
+      schema:
+        type: integer
 security:
   - ApiKeyAuthHeader: []
   - ApiKeyAuthQuery: []