APIFreaks - API Hub for Developers PDF Template APIs API

openapi: 3.2.0
info:
  title: Apifreaks Api Hub For Developers PDF Template APIs API
  version: 1.0.0
  contact:
    name: APIFreaks Support
    url: https://apifreaks.com/contact
    email: support@apifreaks.com
  description: 'Operations tagged PDF Template APIs across 2 of this provider''s published API definitions: apifreaks-api-hub-for-developers-pdf-generator-bulk-openapi.json, apifreaks-api-hub-for-developers-pdf-generator-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.apifreaks.com/v1.0
  description: PDF Generator API Server
security:
- ApiKeyAuthHeader: []
- ApiKeyAuthQuery: []
tags:
- name: PDF Template APIs
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'
          headers:
            X-AF-Credits-Cost:
              $ref: '#/components/headers/X-AF-Credits-Cost'
        '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.
          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/bulk
                    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'
          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'
          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'
          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'
          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'
          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'
          headers:
            X-AF-Credits-Cost:
              $ref: '#/components/headers/X-AF-Credits-Cost'
      operationId: generatePdfsFromCsv
    servers:
    - url: https://api.apifreaks.com/v1.0
      description: PDF Generator API Server
  /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
    servers:
    - url: https://api.apifreaks.com/v1.0
      description: PDF Generator API Server
components:
  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).
    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.
  headers:
    X-AF-Credits-Cost:
      description: Specifies the number of credits consumed by the current request.
      schema:
        type: integer
  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.
x-refined-from:
- apifreaks-api-hub-for-developers-pdf-generator-bulk-openapi.json
- apifreaks-api-hub-for-developers-pdf-generator-openapi.json