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;
}

// 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 default is all pages.
  pages?: Pages;
  actions?: Action[];
};

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

type Part = FilePart | HTMLPart;

type PDFOutput = {
  type: "pdf";
}

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 | 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

--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--

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.