openapi_draft.yml

openapi: 3.0.0
info:
  title: FileForge API
  description: FileForge API for document operations.
  version: 0.1.0
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header
  schemas:
    def-0:
      type: object
      required:
        - statusCode
        - code
        - message
      description: Generic error response schema
      properties:
        statusCode:
          type: number
          description: The HTTP status code
          example: 400
        code:
          type: string
          description: A machine-readable error code
          example: BAD_REQUEST
        message:
          type: string
          description: A human-readable message. This field may also provide additional
            context to the error code.
          example: Bad request
      title: ErrorSchema
paths:
  /status/:
    get:
      operationId: getStatus
      description: Get the status of the API
      x-fern-availability: generally-available
      responses:
        "200":
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
  /pdf/docx/:
    post:
      operationId: convertDOCXtoPDF
      summary: Converts a DOC or DOCX document to PDF.
      tags:
        - PDF
      description: >-
        Converts a Microsoft Word document (.DOCX or .DOC) file to a PDF
        document.


        This service uses a LibreOffice headless server to perform the
        conversion, and may not support all features of the original document.


        **Known discrepancies**


        * Some fonts may not be available in the server, and may be substituted
        by a closest match.

        * Some complex formatting may not be preserved, such as background
        graphics.


        **Variables**


        Variable replacement is supported with various methods:


        * Templated litterals: `{{name}}`

        * Word variables, as listed in the document metadata: `{DOCVARIABLE
        "name"}`


        To enable variable replacement as Word variables for your account,
        please contact the FileForge support.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                options:
                  description: >-
                    Conversion options. This field is required even if empty.


                    **Options**


                    * `templateLiterals`: Map of template literals to replace in
                    the document. Template literals should be enclosed in double
                    curly braces, e.g. `{{name}}`. Variables name can contain
                    alphanumeric characters and hyphens. All variables are
                    case-sensitive. The value for each variable should be a
                    string. If a value of undefined is passed, the variable will
                    not be removed from the document. If you need to remove a
                    variable, pass an empty string as the value.


                    **NB** variables should **not** have surrounding spaces,
                    e.g. `{{ name }}`.


                    **Example**


                    In the Word document: `{{name}} {{nickname}}. was born on
                    {{date}}.`


                    ```json

                    {
                      "templateLiterals": {
                        "name": "John Doe",
                        "date": "2021-12-31",
                        "nickname": ""
                      }
                    }

                    ```


                    There will not be an error if a variable is not found in the
                    document, nor if variables found in the document are not in
                    the options.
                  type: object
                  properties:
                    keepOriginalStyles:
                      type: boolean
                      description: Whether to keep the text formatting of the variables in the
                        document. Default is true.
                    templateLiterals:
                      type: object
                      description: Map of template literals to replace in the document.
                      additionalProperties:
                        type: string
                file:
                  description: The Microsoft Word document (.DOCX or .DOC) file to convert to PDF.
                  type: string
                  format: binary
            encoding:
              options:
                contentType: application/json
        required: true
      security:
        - apiKey: []
      x-fern-sdk-group-name:
        - pdf
      x-fern-sdk-method-name: fromDocx
      x-fern-availability: beta
      responses:
        "201":
          description: PDF Document generated successfully
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                description: Bad request
                $ref: "#/components/schemas/def-0"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Unauthorized
                $ref: "#/components/schemas/def-0"
        "500":
          description: Internal server error
  /pdf/generate/:
    post:
      operationId: generatePDFDocument
      summary: Generates a PDF document from HTML and web technologies.
      tags:
        - PDF
      description: Generates a PDF document from web assets.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - files
              properties:
                options:
                  description: Conversion options. This field is required even if empty.
                  type: object
                  properties:
                    test:
                      type: boolean
                      description: Generate a test document instead of a production document. The
                        generated document will contain a watermark. Defaults to
                        true.
                      default: true
                    host:
                      type: boolean
                      description: If enabled, the document will be hosted by FileForge and a
                        presigned URL will be returned.
                      default: false
                    expiresAt:
                      type: string
                      format: date-time
                      description: If host is enabled, the expiration date of the presigned URL.
                        Defaults to 7 days from now. Cannot exceed 7 days from
                        now.
                    fileName:
                      type: string
                      description: The name of the generated PDF file. Defaults to document. The file
                        name should not contain extensions nor path traversals.
                      default: document
                files:
                  description: >-
                    Files to generate the PDF document from.


                    An `index.html` file is required, and will be used as the
                    main document. Other documents may also be attached, such as
                    stylesheets or images. The path in the `filename` part of
                    the multipart attachement will be respected during
                    generation.


                    **Important notice**: during generation, the `index.html`
                    file will be processed to include the base URL of the
                    document. This is required for assets to be loaded
                    correctly. To link your assets from the HTML file, you
                    should not use a leading slash in the URL. For example, use
                    `<img src="image.jpg" />` instead of `<img src="/image.jpg"
                    />`.
                  allOf:
                    - {}
                    - type: array
                      items:
                        type: string
                        format: binary
            encoding:
              options:
                contentType: application/json
        required: true
      security:
        - apiKey: []
      x-fern-sdk-group-name:
        - pdf
      x-fern-sdk-method-name: generate
      x-fern-availability: generally-available
      responses:
        "201":
          description: PDF Document generated successfully
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: object
                required:
                  - url
                properties:
                  url:
                    type: string
                    format: uri
                    description: URL to the generated PDF document
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                description: Bad request
                $ref: "#/components/schemas/def-0"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Unauthorized
                $ref: "#/components/schemas/def-0"
        "500":
          description: Internal server error
        "502":
          description: Bad Gateway
          content:
            application/json:
              schema:
                description: Bad Gateway
                $ref: "#/components/schemas/def-0"
  /pdf/merge/:
    post:
      operationId: mergePDFDocuments
      tags:
        - PDF
      description: Merges multiple PDF documents into a single PDF document.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - files
              properties:
                options:
                  type: object
                  properties: {}
                files:
                  allOf:
                    - {}
                    - type: array
                      items:
                        type: string
                        format: binary
            encoding:
              options:
                contentType: application/json
        required: true
      security:
        - apiKey: []
      x-fern-sdk-group-name:
        - pdf
      x-fern-sdk-method-name: merge
      x-fern-availability: generally-available
      responses:
        "201":
          description: PDF Document generated successfully
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                description: Bad request
                $ref: "#/components/schemas/def-0"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Unauthorized
                $ref: "#/components/schemas/def-0"
        "500":
          description: Internal server error
  /pdf/form/detect/:
    post:
      operationId: detectPDFFormFields
      summary: Detect form fields in a PDF document
      tags:
        - PDF
        - form
      description: Returns a list of form fields detected in the PDF document, along
        with their location, options and requirements. For a more visual
        representation, use the /pdf/form/mark endpoint.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                options:
                  type: object
                  properties: {}
                file:
                  type: string
                  format: binary
            encoding:
              options:
                contentType: application/json
        required: true
      security:
        - apiKey: []
      x-fern-sdk-group-name:
        - pdf
        - form
      x-fern-sdk-method-name: detect
      x-fern-availability: beta
      responses:
        "200":
          description: Document fields detected successfully
          content:
            application/json:
              schema:
                description: Document fields detected successfully
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    required:
                      type: boolean
                    readOnly:
                      type: boolean
                    locations:
                      type: array
                      items:
                        type: object
                        properties:
                          x:
                            type: number
                          y:
                            type: number
                          width:
                            type: number
                          height:
                            type: number
                        required:
                          - x
                          - y
                          - width
                          - height
                  required:
                    - name
                    - type
                    - required
                    - readOnly
                    - locations
                  anyOf:
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - PDFCheckBox
                        isChecked:
                          type: boolean
                      required:
                        - type
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - PDFDropdown
                            - PDFOptionList
                        options:
                          type: array
                          items:
                            type: string
                        isMultiselect:
                          type: boolean
                        selected:
                          type: array
                          items:
                            type: string
                        isEditable:
                          type: boolean
                      required:
                        - type
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - PDFRadioGroup
                        options:
                          type: array
                          items:
                            type: string
                        selected:
                          type: string
                        isMutuallyExclusive:
                          type: boolean
                        isOffToggleable:
                          type: boolean
                      required:
                        - type
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - PDFTextField
                        defaultValue:
                          type: string
                        isPassword:
                          type: boolean
                        isRichFormatted:
                          type: boolean
                        isScrollable:
                          type: boolean
                        isCombed:
                          type: boolean
                        isMultiline:
                          type: boolean
                        isFileSelector:
                          type: boolean
                        maxLength:
                          type: number
                      required:
                        - type
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                description: Bad request
                $ref: "#/components/schemas/def-0"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Unauthorized
                $ref: "#/components/schemas/def-0"
        "500":
          description: Internal server error
  /pdf/form/mark/:
    post:
      operationId: markPDFFormFields
      summary: Mark form fields in a PDF document
      tags:
        - PDF
        - form
      description: Returns a modified PDF document with form fields marked with a
        green border, and hover text showing the field name.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                options:
                  type: object
                  properties: {}
                file:
                  type: string
                  format: binary
            encoding:
              options:
                contentType: application/json
        required: true
      security:
        - apiKey: []
      x-fern-sdk-group-name:
        - pdf
        - form
      x-fern-sdk-method-name: mark
      x-fern-availability: beta
      responses:
        "201":
          description: Marked PDF Document generated successfully
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                description: Bad request
                $ref: "#/components/schemas/def-0"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Unauthorized
                $ref: "#/components/schemas/def-0"
        "500":
          description: Internal server error
  /pdf/form/fill/:
    post:
      operationId: fillPDFFormFields
      summary: Fill form fields in a PDF document
      tags:
        - PDF
        - form
      description: Returns a modified PDF document with filled form fields. A subset
        of fields can be filled.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                options:
                  type: object
                  required:
                    - fields
                  properties:
                    fields:
                      type: array
                      description: Fields to fill or change in the PDF document.
                      items:
                        type: object
                        anyOf:
                          - type: object
                            required:
                              - name
                              - type
                              - value
                            properties:
                              name:
                                description: Name of the field to fill. This must match an exact name from the
                                  PDF document. To detect all fields, use the
                                  /pdf/form/fields endpoint, or use the
                                  /pdf/form/mark endpoint to get an annotated
                                  PDF with each detected field.
                                type: string
                              type:
                                type: string
                                enum:
                                  - PDFTextField
                              value:
                                type: string
                          - type: object
                            required:
                              - name
                              - type
                              - checked
                            properties:
                              name:
                                description: Name of the field to fill. This must match an exact name from the
                                  PDF document. To detect all fields, use the
                                  /pdf/form/fields endpoint, or use the
                                  /pdf/form/mark endpoint to get an annotated
                                  PDF with each detected field.
                                type: string
                              type:
                                type: string
                                enum:
                                  - PDFCheckBox
                              checked:
                                type: boolean
                          - type: object
                            required:
                              - name
                              - type
                              - selected
                            properties:
                              name:
                                description: Name of the field to fill. This must match an exact name from the
                                  PDF document. To detect all fields, use the
                                  /pdf/form/fields endpoint, or use the
                                  /pdf/form/mark endpoint to get an annotated
                                  PDF with each detected field.
                                type: string
                              type:
                                type: string
                                enum:
                                  - PDFOptionList
                                  - PDFDropdown
                              selected:
                                type: array
                                items:
                                  type: string
                          - type: object
                            required:
                              - name
                              - type
                              - selected
                            properties:
                              name:
                                description: Name of the field to fill. This must match an exact name from the
                                  PDF document. To detect all fields, use the
                                  /pdf/form/fields endpoint, or use the
                                  /pdf/form/mark endpoint to get an annotated
                                  PDF with each detected field.
                                type: string
                              type:
                                type: string
                                enum:
                                  - PDFRadioGroup
                              selected:
                                type: string
                file:
                  type: string
                  format: binary
            encoding:
              options:
                contentType: application/json
        required: true
      security:
        - apiKey: []
      x-fern-sdk-group-name:
        - pdf
        - form
      x-fern-sdk-method-name: fill
      x-fern-availability: beta
      responses:
        "201":
          description: PDF Document filled successfully
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                description: Bad request
                $ref: "#/components/schemas/def-0"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Unauthorized
                $ref: "#/components/schemas/def-0"
        "500":
          description: Internal server error
servers:
  - url: https://api.fileforge.com
    description: Tunnel server
  - url: http://localhost:3000
    description: Development server
tags:
  - name: PDF
    description: PDF operations
  - name: form
    description: PDF form operations