Knowledge Base

API Endpoints

POST /v2/previews/

Returned response can be used for polling until results are available and return an HTTP status code of 200. If application has a Callback URL specified, results will also be posted via webhooks.

Example Request

$ curl https://api.filepreviews.io/v2/previews/ \
  -X POST \
  -H "Content-Type: application/json" \
  -u API_KEY:API_SECRET \
  -d '{"url":"https://www.filepicker.io/api/file/0ehaqJwCTSq4P6jMrix6"}'

Example Response

{
  "id": "42764e04-9094-467c-96b3-49d31ff4423d",
  "url": "https://api.filepreviews.io/v2/previews/42764e04-9094-467c-96b3-49d31ff4423d/",
  "status": "pending",
  "preview": null,
  "thumbnails": null,
  "original_file": null,
  "user_data": null
}
Name Required Description
url Supported Feature Icon

The direct publicly accessible URL of the file to generate previews. This can be a temporary signed Amazon S3/Cloudfront URL or contain basic authentication credentials.

sizes

An array of sizes of the extracted thumbnails, in pixels. Expressed as widthxheight. Specifying only the width(e.g "300") will generate a thumbnail with a fixed width and varying height. You can also only shrink larger images to fit into the give size and never enlarge(e.g "300x400>").

format

The format of the extracted thumbnails. Supported values are "jpg", "jpeg", and "png".

metadata

An array of string values of additional metadata to extract. Possible values are "ocr", "psd", "exif", "ocr", "checksum", "multimedia", "webpage", and "sketch".

pages

The document pages that you want to extract thumbnails for. You can specify a range or individual pages separated by commas. Example: "1-3" or "1,3,5". You can also specify the special value of "all" to extract all pages. Default value is "1".

data

A user-specified JavaScript object to attach key-value data. This is useful for storing additional structured information. As an example, you could store a unique identifier from your system that a FilePreviews response belongs to.

uploader

A JavaScript object containing settings for the AWS S3 uploader. Available options:

destination - The path at which the file is to be stored. Example: cards/1

headers - A JavaScript object containing a list of headers to be set for this file on S3. You can find a list of available headers that can be used.

callback_url

A URL that we will POST anytime results for requests previews are ready. Read more info about webhooks here.

GET /v2/previews/<id>/

Returned response can be used for polling until results are available and return an HTTP status code of 200. If application has a Callback URL specified, results will also be posted via webhooks.

Example Request

$ curl https://api.filepreviews.io/v2/previews/42764e04-9094-467c-96b3-49d31ff4423d/ \
  -u API_KEY:API_SECRET

Example Response

{
  "id": "e093af1f-c21b-41d4-a68f-8cd859bf893a",
  "url": "https://api.filepreviews.io/v2/previews/e093af1f-c21b-41d4-a68f-8cd859bf893a/",
  "status": "success",
  "preview": {
    "page": 1,
    "size": {
      "height": "792",
      "width": "612"
    },
    "resized": false,
    "original_size": {
      "height": "792",
      "width": "612"
    },
    "url": "https://s3.amazonaws.com/demo.filepreviews.io/d8b062537d967a2dc44cac8849279c8b31d5b395128408af70ce59c1529fc32b/user_manual_original_1.png",
    "requested_size": "original"
  },
  "thumbnails": [{
    "page": 1,
    "size": {
      "height": "792",
      "width": "612"
    },
    "resized": false,
    "original_size": {
      "height": "792",
      "width": "612"
    },
    "url": "https://s3.amazonaws.com/demo.filepreviews.io/d8b062537d967a2dc44cac8849279c8b31d5b395128408af70ce59c1529fc32b/user_manual_original_1.png",
    "requested_size": "original"
  }],
  "original_file": {
    "name": "user_manual",
    "size": 416905,
    "total_pages": 1,
    "metadata": null,
    "extension": "pdf",
    "encoding": "binary",
    "mimetype": "application/pdf",
    "type": "application"
  },
  "user_data": null
}