openapi: 3.0.0
info:
  title: PDF Blocks API
  description: 'PDF Blocks is a secure, reliable, and fast API to work with PDF documents. Actions include: Merge PDF documents, add or remove passwords, add watermarks, remove, extract, reverse, and rotate pages, and more.'
  termsOfService: https://www.pdfblocks.com/terms
  contact:
    name: PDF Blocks Support
    url: https://www.pdfblocks.com/support
    email: support@pdfblocks.com
  version: '1.5.0'
servers:
  - url: https://api.pdfblocks.com
    description: Global endpoint (default).
  - url: https://eu.api.pdfblocks.com
    description: European-only endpoint.
paths:
  /v1/add_password:
    post:
      summary: Add a password to a PDF
      description: Protect a PDF document with a password. Encrypt the PDF document to prevent unauthorized access.
      externalDocs:
        description: Documentation and examples
        url: https://www.pdfblocks.com/docs/api/v1/add-password
      operationId: addPasswordV1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The input PDF document
                  type: string
                  format: binary
                password:
                  description: The password required to open the file.
                  type: string
                  minLength: 4
                  maxLength: 32
                  pattern: ^[\x20-\x7e]{4,32}$
                  example: pa$$word
                encryption_algorithm:
                  description: The algorithm used to encrypt the PDF document.
                  type: string
                  enum:
                    - AES-128
                    - AES-256
                  default: AES-128
                  example: AES-128
              required:
                - file
                - password
        required: true
      responses:
        '200':
          $ref: '#/components/responses/success'
        '4XX':
          $ref: '#/components/responses/error'
  /v1/add_watermark/text:
    post:
      summary: Add a text watermark to a PDF
      description: Add a text watermark to each page of a PDF document. Choose from several watermark templates.
      externalDocs:
        description: Documentation and examples
        url: https://www.pdfblocks.com/docs/api/v1/add-watermark-text
      operationId: addTextWatermarkV1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The input PDF document
                  type: string
                  format: binary
                line_1:
                  description: The first line of text of the watermark.
                  type: string
                  maxLength: 32
                  example: Jane Doe
                line_2:
                  description: The second line of text of the watermark.
                  type: string
                  maxLength: 32
                  example: ACME, Inc
                line_3:
                  description: The third line of text of the watermark.
                  type: string
                  maxLength: 32
                  example: Confidential
                template:
                  description: 'The [id of the text watermark template](https://www.pdfblocks.com/docs/api/v1/text-watermark-templates.pdf).'
                  type: integer
                  format: int32
                  minimum: 1001
                  maximum: 66537
                  default: 1001
                  example: 1001
                color:
                  description: The color of the text watermark.
                  type: string
                  enum:
                    - Red
                    - Blue
                    - Gray
                    - Black
                  default: Gray
                  example: Gray
                transparency:
                  description: The transparency level for the text watermark from 0 (opaque) to 100 (transparent).
                  type: integer
                  format: int32
                  minimum: 0
                  maximum: 100
                  default: 75
                  example: 75
                margin:
                  description: The distance in inches from the border of the page to the text watermark.
                  type: number
                  format: float
                  minimum: 0.0
                  default: 1.0
                  example: 1.0
              required:
                - file
                - line_1
        required: true
      responses:
        '200':
          $ref: '#/components/responses/success'
        '4XX':
          $ref: '#/components/responses/error'
  /v1/add_watermark/image:
    post:
      summary: Add an image watermark to a PDF
      description: Add an image watermark to each page of a PDF document.
      externalDocs:
        description: Documentation and examples
        url: https://www.pdfblocks.com/docs/api/v1/add-watermark-image
      operationId: addImageWatermarkV1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The input PDF document
                  type: string
                  format: binary
                image:
                  description: The image to add as a watermark. The format of the image can be either PNG or JPEG.
                  type: string
                  format: binary
                transparency:
                  description: The transparency level for the image watermark from 0 (opaque) to 100 (transparent).
                  type: integer
                  format: int32
                  minimum: 0
                  maximum: 100
                  default: 50
                  example: 50
                margin:
                  description: The distance in inches from the border of the page to the image watermark.
                  type: number
                  format: float
                  minimum: 0.0
                  default: 1.0
                  example: 1.0
              required:
                - file
                - image
        required: true
      responses:
        '200':
          $ref: '#/components/responses/success'
        '4XX':
          $ref: '#/components/responses/error'
  /v1/merge_documents:
    post:
      summary: Merge PDF documents
      description: Combine multiple PDF documents into a single PDF document.
      externalDocs:
        description: Documentation and examples
        url: https://www.pdfblocks.com/docs/api/v1/merge-documents
      operationId: mergeDocumentsV1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The array of PDF documents. PDF documents will be merged in the same order they are inserted into this array.
                  type: array
                  items:
                    description: An input PDF document.
                    type: string
                    format: binary
        required: true
      responses:
        '200':
          $ref: '#/components/responses/success'
        '4XX':
          $ref: '#/components/responses/error'
  /v1/extract_pages:
    post:
      summary: Extract pages from a PDF
      description: Extract one or more pages from a PDF document.
      externalDocs:
        description: Documentation and examples
        url: https://www.pdfblocks.com/docs/api/v1/extract-pages
      operationId: extractPagesV1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The input PDF document
                  type: string
                  format: binary
                first_page:
                  description: The first page of the range to extract. If empty, it defaults to the first page of the PDF document.
                  type: integer
                  format: int32
                  minimum: 1
                last_page:
                  description: The last page of the range to extract. If empty, it defaults to the last page of the PDF document.
                  type: integer
                  format: int32
                  minimum: 1
              required:
                - file
        required: true
      responses:
        '200':
          $ref: '#/components/responses/success'
        '4XX':
          $ref: '#/components/responses/error'
  /v1/remove_pages:
    post:
      summary: Remove pages from a PDF
      description: Remove one or more pages from a PDF document.
      externalDocs:
        description: Documentation and examples
        url: https://www.pdfblocks.com/docs/api/v1/remove-pages
      operationId: removePagesV1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The input PDF document
                  type: string
                  format: binary
                first_page:
                  description: The first page of the range to remove from the PDF document. If empty, it defaults to the first page of the document.
                  type: integer
                  format: int32
                  minimum: 1
                last_page:
                  description: The last page of the range to remove from the PDF document. If empty, it defaults to the last page of the document.
                  type: integer
                  format: int32
                  minimum: 1
              required:
                - file
        required: true
      responses:
        '200':
          $ref: '#/components/responses/success'
        '4XX':
          $ref: '#/components/responses/error'
  /v1/rotate_pages:
    post:
      summary: Rotate pages in a PDF
      description: Rotate one or more pages in a PDF document.
      externalDocs:
        description: Documentation and examples
        url: https://www.pdfblocks.com/docs/api/v1/rotate-pages
      operationId: rotatePagesV1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The input PDF document
                  type: string
                  format: binary
                angle:
                  description: The angle of rotation of the pages. Positive angles rotate the pages clockwise. Negative angles rotate the pages counter-clockwise.
                  type: integer
                  format: int32
                  enum:
                    - 0
                    - 90
                    - 180
                    - 270
                    - -90
                    - -180
                    - -270
                  example: 90
                first_page:
                  description: The first page of the range to rotate in the PDF document. If empty, it defaults to the first page of the document.
                  type: integer
                  format: int32
                  minimum: 1
                last_page:
                  description: The last page of the range to rotate in the PDF document. If empty, it defaults to the last page of the document.
                  type: integer
                  format: int32
                  minimum: 1
              required:
                - file
                - angle
        required: true
      responses:
        '200':
          $ref: '#/components/responses/success'
        '4XX':
          $ref: '#/components/responses/error'
  /v1/add_restrictions:
    post:
      summary: Add restrictions to a PDF
      description: Add restrictions to prevent copying, printing, and modifying a PDF document.
      externalDocs:
        description: Documentation and examples
        url: https://www.pdfblocks.com/docs/api/v1/add-restrictions
      operationId: addRestrictionsV1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The input PDF document
                  type: string
                  format: binary
                owner_password:
                  description: The password required to open and change permissions of the PDF document.
                  type: string
                  minLength: 4
                  maxLength: 32
                  pattern: ^[\x20-\x7e]{4,32}$
                  example: pa$$word
                user_password:
                  description: The password required to open the PDF document. If the `user_password` is not set, the user will be able to open the document without a password.
                  type: string
                  minLength: 4
                  maxLength: 32
                  pattern: ^[\x20-\x7e]{4,32}$
                  example: pa$$word
                encryption_algorithm:
                  description: The algorithm used to encrypt the PDF document.
                  type: string
                  enum:
                    - AES-128
                    - AES-256
                  default: AES-128
                  example: AES-128
                allow_copy_content:
                  description: If false, the user can't copy text and images to the clipboard.
                  type: boolean
                  default: true
                allow_change_content:
                  description: If false, the user can't change the content of the document.
                  type: boolean
                  default: true
                allow_print:
                  description: If false, the user can't print the document.
                  type: boolean
                  default: true
                allow_print_high_resolution:
                  description: If false, the user can't print the document in high resolution.
                  type: boolean
                  default: true
                allow_comment_and_fill_form:
                  description: If false, the user can't add, edit or modify annotations or fill form fields.
                  type: boolean
                  default: true
                allow_fill_form:
                  description: If false, the user can't fill forms fields.
                  type: boolean
                  default: true
                allow_assemble_document:
                  description: If false, the user can't assemble or manipulate the document.
                  type: boolean
                  default: true
                allow_accessibility:
                  description: If false, accessibility programs can't read the text or images of the document.
                  type: boolean
                  default: true
              required:
                - file
                - owner_password
        required: true
      responses:
        '200':
          $ref: '#/components/responses/success'
        '4XX':
          $ref: '#/components/responses/error'
  /v1/remove_password:
    post:
      summary: Remove the password from a PDF
      description: Remove the password from an encrypted PDF document. The PDF document will no longer require a password to open.
      externalDocs:
        description: Documentation and examples
        url: https://www.pdfblocks.com/docs/api/v1/remove-password
      operationId: removePasswordV1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The input PDF document
                  type: string
                  format: binary
                password:
                  description: The password required to open the file.
                  type: string
                  maxLength: 256
                  example: pa$$word
              required:
                - file
                - password
        required: true
      responses:
        '200':
          $ref: '#/components/responses/success'
        '4XX':
          $ref: '#/components/responses/error'
  /v1/remove_restrictions:
    post:
      summary: Remove the restrictions from a PDF
      description: Remove all the restrictions from a PDF document.
      externalDocs:
        description: Documentation and examples
        url: https://www.pdfblocks.com/docs/api/v1/remove-restrictions
      operationId: removeRestrictionsV1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The input PDF document
                  type: string
                  format: binary
              required:
                - file
        required: true
      responses:
        '200':
          $ref: '#/components/responses/success'
        '4XX':
          $ref: '#/components/responses/error'
  /v1/remove_signatures:
    post:
      summary: Remove the signatures from a PDF
      description: Remove the cryptographic signatures and timestamps from a PDF document.
      externalDocs:
        description: Documentation and examples
        url: https://www.pdfblocks.com/docs/api/v1/remove-signatures
      operationId: removeSignaturesV1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The input PDF document
                  type: string
                  format: binary
              required:
                - file
        required: true
      responses:
        '200':
          $ref: '#/components/responses/success'
        '4XX':
          $ref: '#/components/responses/error'
  /v1/reverse_pages:
    post:
      summary: Reverse the pages of a PDF
      description: Reverse the order of the pages of a PDF document.
      externalDocs:
        description: Documentation and examples
        url: https://www.pdfblocks.com/docs/api/v1/reverse-pages
      operationId: reversePagesV1
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The input PDF document
                  type: string
                  format: binary
              required:
                - file
        required: true
      responses:
        '200':
          $ref: '#/components/responses/success'
        '4XX':
          $ref: '#/components/responses/error'
components:
  responses:
    success:
      description: The document was processed succesfully.
      content:
        application/pdf:
          schema:
            description: The output PDF document
            type: string
            format: binary
    error:
      description: Error
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: url
              title:
                type: string
              status:
                type: integer
              errors:
                type: object
          example:
            type: https://www.pdfblocks.com/docs/api/v1/error/400
            title: One or more validation errors occurred.
            status: 400
            errors:
              file:
                - Could not parse the PDF document. The file may be invalid or corrupt.
  securitySchemes:
    apiKey:
      type: apiKey
      description: 'Find your API key in [your dashboard](https://dashboard.pdfblocks.com/users/sign_in), or [get a free API key](https://www.pdfblocks.com/try-free).'
      name: X-Api-Key
      in: header
security:
  - apiKey: []
externalDocs:
  description: Documentation and examples
  url: https://www.pdfblocks.com/docs/api/v1