@apifreaks/openapi-specs 0.1.2 → 0.2.0

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

@@ -0,0 +1,199 @@
+openapi: 3.1.1
+info:
+  title: PDF Generator API - Bulk PDF Generation from CSV
+  version: 1.0.0
+  description: Generate one PDF per row from an uploaded CSV file against a template you designed in the APIFreaks PDF Template Builder. Each row is processed independently, and the response returns an array of results, each with its own pdf_url. 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/bulk:
+    post:
+      tags:
+        - PDF Template APIs
+      summary: Generate PDFs in bulk from a CSV
+      description: Upload a CSV file where each row is one record. The API generates one PDF per row and returns an array of results, each with its own pdf_url. Rows are processed independently, so a failure in one row does not block the rest of the batch. The response gives a row-by-row breakdown of which PDFs succeeded and which failed.
+      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.
+      requestBody:
+        description: Multipart form-data body carrying the CSV file to render. Each row in the CSV is one record and produces one PDF.
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/CsvUploadRequest'
+      responses:
+        '200':
+          description: PDFs generated successfully. The response is an array of results, one entry per CSV row, each with its own pdf_url.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/TemplateGenerationResponse'
+              examples:
+                success:
+                  summary: Generated PDFs for two rows
+                  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_20260810141245054106_1.pdf
+                      created_at: '2026-08-10T14:12:47.887Z'
+                      expiration_time: '2026-11-10T14:12:47.887Z'
+                    - 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_20260810141245054154_2.pdf
+                      created_at: '2026-08-10T14:12:47.940Z'
+                      expiration_time: '2026-11-10T14:12:47.940Z'
+        '400':
+          description: Bad Request — Missing parameters, a file that is not a CSV, or data larger than 10 MB.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                CsvFileRequired:
+                  summary: Uploaded file is not a CSV
+                  value:
+                    timestamp: '2026-08-10T14:13:14.497Z'
+                    path: /v1.0/generate-pdf/bulk
+                    status: 400
+                    error: CSV File Required
+                    message: Only CSV files are supported. Please upload a valid CSV file.
+        '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/bulk
+                    status: 401
+                    timestamp: '2026-08-10T14:13:14.996Z'
+        '403':
+          description: Forbidden — The account does not have access to this template.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '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'
+        '415':
+          description: Unsupported Media Type — The request Content-Type is not supported for this endpoint.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '422':
+          description: Unprocessable Entity — The request contains invalid or missing data.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal Server Error — An unexpected error occurred, or the PDF could not be generated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '504':
+          description: Gateway Timeout — The request went past the 100 second processing limit.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      operationId: generatePdfsFromCsv
+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).
+    CsvUploadRequest:
+      type: object
+      description: Multipart form-data request body containing the CSV file to render in bulk.
+      required:
+        - file
+      properties:
+        file:
+          type: string
+          format: binary
+          description: A CSV file uploaded as form-data where each row is one record. One PDF is generated per row.
+    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-generator.yaml

@@ -0,0 +1,316 @@
+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'
+        '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.
+        '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'
+        '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.
+        '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.
+        '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.
+        '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.
+        '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.
+        '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.
+      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).
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apifreaks/openapi-specs",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Public OpenAPI 3.1 specifications for all APIFreaks API products.",
   "type": "module",
   "main": "./dist/index.js",