API Reference

// For actions, each action has additional other properties discussed in the
// relevant guides.
type Action = {
  type: string;
}

// Part related types

// Represents one part that was sent in the multipart request. Should be the
// `name` that was specified for the part.
type MultipartReference = string;

// The page index can be negative, indicating an offset from the last page, with -1
// being the last page itself.
type PageIndex = number | "first" | "last";

type Pages = {
  start?: PageIndex
  end?: PageIndex
}

type FilePart = {
  file: MultipartReference;
  // The password, if the file is password protected.
  password?: string;
  // The default is all pages.
  pages?: Pages;
  actions?: Action[];
};

type Orientation =
  | "landscape"
  | "portrait";

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

type Layout = {
  orientation?: Orientation;
  // The width and the height in mm or a page size preset.
  size?:
    | {
        width: number;
        height: number;
      }
    | PageSize;
  // Margin sizes in mm.
  margin?: {
    left: number;
    top: number;
    right: number;
    bottom: number;
  };
};

type HTMLPart = {
  html: MultipartReference;
  assets? MultipartReference[];
  actions?: Action[];
  layout?: Layout;
}

type NewPagePart = {
  page: "new";
  // The number of blank pages to add.
  pageCount?: number;
  // The background color of the blank pages. Use predefined color names or RGB, HEX, HSL, RGBA, HSLA values.
  backgroundColor?: string;
  layout?: Layout;
  // The following actions are only applied to the given part and not to the entire document.
  actions?: Action[];
};

type Part = FilePart | HTMLPart | NewPagePart;

// Output related types

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[];
  label: string;
};

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

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";
  // The default conformance level is `pdfa-1b`.
  conformance?:
    | "pdfa-1a"
    | "pdfa-1b"
    | "pdfa-2a"
    | "pdfa-2u"
    | "pdfa-2b"
    | "pdfa-3a"
    | "pdfa-3u"; // We currently only support these 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?: Pages;
  // One of width, height, or dpi needs to be specified.
  width?: number;
  height?: number;
  dpi?: number;
}

type Output = PDFOutput | PDFAOutput | ImageOutput;

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

{
  "parts": [
    {
      "file": "my-first-document",
      "pages": {"start": 0, "end": 0}
    }
  ]
}

POST https://api.pspdfkit.com/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Bearer your_api_key_here

--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json
{
  "parts": [
    {
      "file": "my-first-document",
      "pages": {"start": 0, "end": 0}
    }
  ]
}
--customboundary
Content-Disposition: form-data; name="my-first-document"; filename="my-first-document"
Content-Type: application/pdf

<PDF data>
--customboundary--