Build API Reference for PDF Processor

curl -X POST http://localhost:5000/build \
  -H "Authorization: Token token=secret" \
  -o result.pdf \
  -F document=@document.pdf \
  -F index=@index.html \
  -F logo=@logo.png \
  -F instructions='{
      "parts": [
        {
          "file": "document",
          "pages": {
            "start": 0,
            "end": 0
          },
          "actions": [
            {
              "type": "flatten"
            }
          ]
        },
        {
          "html": "index"
        },
        {
          "page": "new",
          "pageCount": 3,
          "backgroundColor": "green"
        }
      ],
      "actions": [
        {
          "type": "watermark",
          "image": "logo",
          "width": "25%"
        }
      ],
      "output": {
        "type": "pdf"
      }
    }'

curl -X POST http://localhost:5000/build \
  -H "Authorization: Token token=secret" \
  -H "Content-Type: application/json" \
  -o result.pdf \
  --data '{
      "parts": [
        {
          "file": {"url": "https://remote-files-storage/document.pdf"},
          "pages": {
            "start": 0,
            "end": 0
          },
          "actions": [
            {
              "type": "flatten"
            }
          ]
        },
        {
          "html": {"url": "https://remote-files-storage/index.html"}
        },
        {
          "page": "new",
          "pageCount": 3,
          "backgroundColor": "green"
        }
      ],
      "actions": [
        {
          "type": "watermark",
          "image": {"url": "https://remote-files-storage/logo.png"},
          "width": "25%"
        }
      ],
      "output": {
        "type": "pdf"
      }
    }'

type Instructions = {
  parts: Part[];
  actions?: Action[];
  output?: Output;
};

type Part = {
  // The input file that will be used as a source for the part.
  file: InputName | InputUrl;
  // Password of the file, if it's password protected.
  password?: string;
  // The page range to include in the part.
  pages?: {
    // The page index can be negative, indicating an offset from the last page, with -1
    // being the last page itself.
    start?: number | 'first' | 'last';
    end?: number | 'first' | 'last';
  };
  // The following actions will only be applied to the given part, and
  // not the entire document.
  actions?: Action[];
};

type PageSize =
  | 'A0'
  | 'A1'
  | 'A2'
  | 'A3'
  | 'A4'
  | 'A5'
  | 'A6'
  | 'A7'
  | 'A8'
  | 'Letter'
  | 'Legal';

type Part = {
  // The HTML file that will be used as a source for the part.
  html: InputName | InputUrl;
  // All assets imported in the HTML. Reference the name passed in the multipart request.
  assets?: Array<string>;
  layout?: {
    orientation?: 'landscape' | 'portrait';
    size?:
      | {
          width: number;
          height: number;
        }
      | PageSize; // {width, height} in mm or page size preset.
    margin?: {
      // Margin sizes in mm.
      left: number;
      top: number;
      right: number;
      bottom: number;
    };
  };
  actions?: Action[];
};

type Part = {
  page: 'new';
  // The number of blank pages to add.
  pageCount?: number;
  // Background color of the blank pages.
  // Specified with predefined color names,
  // or with RGB, HEX, HSL, RGBA, or HSLA values.
  backgroundColor?: string;
  layout?: {
    orientation?: 'landscape' | 'portrait';
    size?: {
      width: number;
      height: number;
    };
    margin?: {
      left?: number;
      right?: number;
      top?: number;
      bottom?: number;
    };
  };
  // The following actions will only be applied to the given part, and
  // not the entire document.
  actions?: Action[];
};

type Action = {
  type: 'applyInstantJson';
  // The input file in Instant JSON format.
  file: InputName | InputUrl;
};

type Action = {
  type: 'applyXfdf';
  // The input file in XFDF format.
  file: InputName | InputUrl;
};

type Action = {
	type: 'flatten';
	// Optional list of annotation IDs to flatten. These can be annotation IDs or `pdfObjectId`s.
	// If provided, only the annotations with the given IDs will be flattened.
	annotationIds?: string[];
};

type Action = {
  type: 'insertPage';
  // Either one of `afterPageIndex` or `beforePageIndex` is required.
  afterPageIndex?: integer;
  beforePageIndex?: integer;
  pageHeight: number;
  pageWidth: number;
  rotateBy?: 90 | 180 | 270;
  // Background color of the blank pages.
  // Specified with predefined color names,
  // or with RGB, HEX, HSL, RGBA, or HSLA values.
  backgroundColor?: string;
};

type Action = {
  type: 'ocr';
  language: string;
};

type Action = {
  type: 'rotate';
  rotateBy: 90 | 180 | 270;
};

type Action = TextWatermarkAction | ImageWatermarkAction;

type TextWatermarkAction = {
  type: 'watermark';
  text: string;
  // Both width and height are required.
  width: Dimension;
  height: Dimension;
  // Only one out of top or bottom is allowed.
  top?: Position;
  // Only one out of right or left is allowed.
  right?: Position;
  bottom?: Position;
  left?: Position;
  rotation?: integer;
  opacity?: number;
  fontSize?: integer;
  fontColor?: string;
  // `italic` and `bold` are supported styles.
  // They can be used together.
  fontStyle?: string[];
  fontFamily?: string;
};

type ImageWatermarkAction = {
  type: 'watermark';
  // The input image file that will be used as a source for the image watermark.
  image: InputName | InputUrl;
  // Both width and height are required.
  width: Dimension;
  height: Dimension;
  // Only one out of top or bottom is allowed.
  top?: Position;
  // Only one out of right or left is allowed.
  right?: Position;
  bottom?: Position;
  left?: Position;
  rotation?: integer;
  opacity?: number;
};

type Dimension = {
  value: integer;
  unit: 'pt' | '%';
};

type Position = {
  value: integer;
  unit: 'pt' | '%';
};

type Content = {
	fillColor?: string; // default is "#000000"
	overlayText?: string; // default is null
	repeatOverlayText?: boolean; // default is false
	color?: string; // default is "#F82400"
	outlineColor?: string; // default is "#F82400"
	creatorName?: string; // default is null
	customData?: object;
};

type Action = {
	type: 'createRedactions';
	strategy: 'preset' | 'regex' | 'text';
	strategyOptions: PresetOption | RegexOption | TextOption;
	content?: Content; 
};

type PresetOption = {
  preset:
    | 'credit-card-number'
    | 'date'
    | 'email-address'
    | 'international-phone-number'
    | 'ipv4'
    | 'ipv6'
    | 'mac-address'
    | 'north-american-phone-number'
    | 'social-security-number'
    | 'time'
    | 'url'
    | 'us-zip-code'
    | 'vin';
  include_annotations?: boolean;
  case_sensitive?: boolean;
};

type RegexOption = {
  regex: string;
  include_annotations?: boolean;
  case_sensitive?: boolean;
};

type TextOption = {
  text: string;
  include_annotations?: boolean;
  case_sensitive?: boolean;
};

type Action = {
  type: 'applyRedactions';
};

type Output = PDFOutput | PDFAOutput | ImageOutput | JsonContentOutput;

type BasePDFOutput = {
  owner_password?: string;
  user_password?: string;
  user_permissions?: UserPermissions[];
  metadata?: Metadata;
  labels?: Label[];
  optimize?: Optimize;
};

type PDFOutput = BasePDFOutput & { type: 'pdf' };

type PDFAOutput = BasePDFOutput & {
  type: 'pdfa';
  // Default is "pdfa-1b".
  conformance?:
    | 'pdfa-1a'
    | 'pdfa-1b'
    | 'pdfa-2a'
    | 'pdfa-2u'
    | 'pdfa-2b'
    | 'pdfa-3a'
    | 'pdfa-3u'; // The currently supported conformance levels.
  vectorization?: boolean; // `true` by default.
  rasterization?: boolean; // `true` by default.
};

type ImageOutput = {
  type: 'image';
  format: 'jpg' | 'jpeg' | 'png' | 'webp';
  // The default is to render the first page.
  pages?: {
    // The page index can be negative, indicating an offset from the last page, with -1
    // being the last page itself.
    start?: number | 'first' | 'last';
    end?: number | 'first' | 'last';
  };
  // One of width, height, or DPI needs to be specified.
  width?: number;
  height?: number;
  dpi?: number;
};

// Extracts document contents and returns them as a JSON.
type JsonContentOutput = {
  type: 'json-content';
  // When set to true, extracts document text. Text is extracted via OCR process.
  plainText: boolean;
  // When set to true, extracts structured document text. This includes text words, characters, lines, and paragraphs.
  structuredText: boolean;
  // When set to true, extracts key-value pairs detected within the document contents. Example of detected values are phone numbers, email addresses, currencies, numbers, dates.
  keyValuePairs: boolean;
  // When set to true, extracts table data from the document.
  tables: boolean;
  // Specifies the language to be used for OCR text extraction. Supports the same set of languages as OCR action.
  language: string;
}

type UserPermissions =
  | 'printing'
  | 'modification'
  | 'extract'
  | 'annotations_and_forms'
  | 'fill_forms'
  | 'extract_accessibility'
  | 'assemble'
  | 'print_high_quality';

// Represents metadata for a PDF.
type Metadata = {
  title?: string;
  author?: string;
};

// Represents a label and the pages associated with it.
type Label = {
  pages: integer[]; // 0-based page index.
  label: string;
};

// Represents the available compression options for the PDF output.
type Optimize = {
  grayscaleText?: boolean; // `false` by default.
  grayscaleGraphics?: boolean; // `false` by default.
  grayscaleFormFields?: boolean; // `false` by default.
  grayscaleAnnotations?: boolean; // `false` by default.
  disableImages?: boolean; // `false` by default.
  mrcCompression?: boolean; // `false` by default.
  linearize?: boolean; // `false` by default.
  imageOptimizationQuality?: integer; // The range is between 1 and 4, where 1 is low and 4 is very high. The default value is 2.
};