GoNitro Generations API

openapi: 3.2.0
info:
  title: Nitro PDF Services Public Authentication Generations API
  description: 'REST API for Nitro PDF Services: convert, transform, extract, and generate PDF documents, plus async job status/result retrieval. Machine-to-machine OAuth 2.0 client-credentials; short-lived bearer tokens. Assembled by API Evangelist from Nitro''s published per-tool OpenAPI reference fragments; schemas preserved verbatim.'
  version: '1.0'
servers:
- url: https://api.gonitro.dev
  description: API server
security:
- BearerAuth: []
tags:
- name: Generations
paths:
  /generations:
    post:
      tags:
      - Generations
      summary: Fill Forms
      description: 'Generate PDF document with filled form fields


        This endpoint is polymorphic: the operation performed is selected by the request body. Documented tools on this endpoint: create-fillable-forms, fill-forms.'
      parameters:
      - name: Accept
        in: header
        schema:
          $ref: '#/components/schemas/AcceptHeader'
      - name: Prefer
        in: header
        schema:
          $ref: '#/components/schemas/PreferHeader'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                method:
                  type: string
                  description: 'The Generations'' endpoint method: `fill-forms`'
                  default: fill-forms
                  enum:
                  - fill-forms
                params:
                  $ref: '#/components/schemas/FormFillParams'
                file:
                  type: string
                  format: binary
                  description: The source PDF document when using inline field values via `params.fields`. Use this parameter when providing form field values directly instead of a data file.
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: The source PDF and data file when using a data file. `files[0]` is the source PDF document (application/pdf). `files[1]` is the data file containing form field values (CSV, JSON, XFDF, or FDF format).
                delivery:
                  $ref: '#/components/schemas/DeliverySingleFileOut'
              required:
              - method
              - params
      responses:
        '200':
          description: 'Returns either JSON or binary output depending on the Accept header (defaults to JSON).

            JSON responses include a file URL for synchronous tasks or a job status for asynchronous tasks.'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PlatformOperationFileResult'
                - $ref: '#/components/schemas/AsyncJobResponse'
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/ContentTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - BearerAuth: []
      operationId: generateDocument
      x-nitro-tools:
      - create-fillable-forms
      - fill-forms
components:
  schemas:
    PreferHeader:
      type: string
      enum:
      - respond-async
      description: 'Controls synchronous vs asynchronous operation. See endpoint description above for behavior details.

        - `respond-async`: Makes request asynchronous, returns job status for polling

        - No value: Synchronous response'
    Header:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
      required:
      - name
      - value
    PlatformOperationFileResult:
      type: object
      title: Sync - Single File
      properties:
        file:
          $ref: '#/components/schemas/FileInfo'
    HTTPCall:
      type: object
      properties:
        URL:
          type: string
          description: Your delivery endpoint URL
          format: uri
        verb:
          type: string
          description: The HTTP method
          default: PUT
          enum:
          - GET
          - POST
          - PUT
          - DELETE
          - PATCH
        headers:
          type:
          - array
          - 'null'
          description: Headers your file delivery endpoint might need (Optional)
          items:
            $ref: '#/components/schemas/Header'
      required:
      - URL
      - verb
    FileInfo:
      type: object
      properties:
        URL:
          type:
          - string
          - 'null'
          format: uri
          description: URL with processed file for download. Field will be `null` if `delivery` parameter for post-processing upload is defined.
        contentType:
          type: string
          description: The file type
          example: application/json
        metadata:
          type: object
          properties:
            fileSizeBytes:
              type:
              - number
              - 'null'
            pageCount:
              type:
              - number
              - 'null'
              description: Number of pages in resulting document.
    DeliverySingleFileOut:
      type: object
      properties:
        uploadResultTo:
          $ref: '#/components/schemas/HTTPCall'
        callback:
          $ref: '#/components/schemas/Callback'
      description: "This endpoint lets you supply your own URL to receive the single-file output. The URL may point to a custom API endpoint or a pre-signed S3 URL. \n\n The HTTP method defaults to PUT, but you can change it based on your implementation needs via the `verb` parameter. You can also provide custom headers, such as authentication headers or any others required by your endpoint."
    FormFillParams:
      title: Fill Forms
      type: object
      properties:
        strict:
          type: boolean
          default: false
          description: Controls validation behavior when filling form fields. When `true`, requests fail with 422 if the input contains unknown field names or omits required fields; when `false`, unrecognized fields are silently ignored and only matching fields are filled.
          example: true
        fields:
          type:
          - array
          - 'null'
          default: null
          description: Inline field name/value pairs to fill, as an alternative to supplying the values in a CSV, JSON, XFDF, or FDF data file.
          items:
            type: object
            properties:
              field:
                type: string
                description: Name of the PDF form field to fill.
              value:
                description: Value to set for the field. May be a string, number, boolean, or null.
                oneOf:
                - type: string
                - type: integer
                - type: number
                - type: boolean
            required:
            - field
            - value
          example:
          - field: firstName
            value: Jane
          - field: lastName
            value: Doe
    AcceptHeader:
      type: string
      enum:
      - application/json
      - application/octet-stream
      - '*/*'
      default: '*/*'
      description: "Controls response format and behavior. See endpoint description above for detailed response combinations.\n- `application/json`: Returns JSON response with operation result\n- `application/octet-stream`: Returns binary file content \n- `*/*`: Defaults to JSON response"
    Callback:
      type: object
      description: POST endpoint that will get JOB ID and location when processing starts only on async processesing (see example above)
      properties:
        URL:
          type: string
          description: Your POST endpoint callback URL.
          format: uri
        headers:
          type: array
          description: Headers your callback endpoint might need
          items:
            $ref: '#/components/schemas/Header'
      required:
      - URL
    AsyncJobResponse:
      type: object
      title: Async - Job
      properties:
        jobID:
          type: string
          example: 01234567-89ab-cdef-0123-456789abcdef
        status:
          type: string
          enum:
          - running
        progress:
          type: number
          description: Progress of the job as a float between 0.0 and 1.0
          format: float
          default: 0
          example: 0
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT