API Reference

When making requests to PSPDFKit API, the instructions object needs to follow this specification:

// 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.
    | {
        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`.
    | "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;

Each request needs to include at least one part, and the request also needs to include all files referenced by the part. For example, to get the first page of a document, you’d supply the following instructions:

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

The request itself then needs to contain a my-first-document part in addition to the instructions part:

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

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

<PDF data>

For more detailed information on how to combine the API and available actions, see the guides for each specific API tool.

Status Codes

PSPDFKit API uses HTTP status codes to communicate success and failure of your requests. We use three main ranges to communicate the result of your requests:

  • 200 — Responses with status code 200 indicate that the API call was successful.
  • 4XX — Responses with status code 4XX indicate that some invalid data was supplied, or a precondition wasn’t met.
  • 5XX — Responses with status code 5XX indicate an internal error with PSPDFKit API itself.

Here’s a list of common status codes in the 4XX range that you can expect, and what they mean:

  • 413 — This status is sent by the API when your request exceeds the maximum input size, meaning either a single part, or the sum of all parts, is too large.
  • 422 — This status is sent by the API when the resulting PDF of your API call exceeded the maximum output file size.
  • 401 — This status is sent by the API when no API token is specified, or when the API token you specified isn’t valid.
  • 402 — This status is sent when you have exceeded the total number of documents processed in your subscription.
  • 400 — This status is sent for any other user error with your requests. Possible response payloads are:
    • { "details": "There was an error with one or more parts of the instructions." } — This error indicates that the supplied instructions are incorrect. See our errors guide for more details.