Pdf.Ninja®

By Maximum.Software

Pdf.Ninja® provides web API functionality for working with PDF files.

v2 v1

Features

  • Read a PDF file from a publicly accessible URL
  • Read a PDF file from a POST request
  • Retrieve PDF attributes such as metadata, page size, etc.
  • Retrieve PDF form fields
  • Fill the form fields in a PDF file with data
  • Generate images of pages in a PDF file
  • Embedding images into a PDF file

Uptime

Please see the status page for API statistics.

Release Log

2.2.0

December 30, 2022

  • Added capabilities endpoint
  • v2: Added field widget location data to info and fields enpoints
  • Updated software stack
  • Other minor improvements

Documentation

Authentication

All requests must provide 64 character randomly generated alphanumeric case-sensitive key used for identifying the user. The key can be obtained using the /api/v2/key endpoint.

PDF files

Files are submitted to the API by supplying a publicly accessible URL to the file along with MD5 sum of file's contents. The API server downloads and caches files for a period of time. When the supplied MD5 sum changes, the files are redownloaded. Additionally, the 'file' endpoint can be used to upload PDF files to the API server which are stored for a period of time. Generated files are returned via fileUrl response parameter that is only valid for a short period of time. Generated files can also be optionally returned directly via HTTP response by setting the 'dumpFile' argument to true or yes.

Request format

Requests must be sent to the API using the GET, POST and PUT methods. Data is needs to be passed in through the URL arguments.

Repsonse format

All responses return JSON object with a boolean 'success' fields. Upon failure, responses contain string 'error' containing the error message.

Success

{"success": true, "...": "..."}

Failure

{"success": false, "error": "..."}

Temporary Failure

{"success": false, "error": "...", "temporary": true}

Limits and Access Tiers

The API access is available in two tiers, each having a different set of limits.

  • New keys per IP: 1 keys / 500 seconds

Free

  • Requests per key: 10 requests / 10 seconds
  • Requests per IP: 10 requests / 10 seconds
  • New files per key: 4 files / 20 seconds
  • Maximum file size: 2 MiB
  • File cache expiration: 86400 seconds
  • File cache size: 4 files
  • Pdf.Ninja® Watermark

Pro (get pro key here)

  • Requests per key: 50 requests / 10 seconds
  • Requests per IP: 50 requests / 10 seconds
  • New files per key: 10 files / 10 seconds
  • Maximum file size: 32 MiB
  • File cache expiration: 604800 seconds
  • File cache size: 50 files
  • No Watermark

Endpoints

GET /api/v2/key

Parameters

Returns a newly generated key.

Request
$ curl "https://pdf.ninja/api/v2/key?email=test@pdf.ninja" Try me
Response
{
    "success": true,
    "key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

POST /api/v2/file

Parameters

Receives and caches a PDF file. File cache is temporary and expires after a period of time. Do not rely on it to store your files. If your file is no longer in the cache then you will get "noSuchFileId" error message, in which case you will need to re-upload the PDF file before retrying the request.

Request
$ curl "https://pdf.ninja/api/v2/file" -F file=@test.pdf -F "fileId=test" -F "md5sum=022cb6201da97ab7b745f88978d4cab7" -F "key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Try me
Response
{"success": true}

GET /api/v2/info

Parameters

Returns information about the PDF file.

Request
$ curl "https://pdf.ninja/api/v2/info?fileId=test&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me $ curl "https://pdf.ninja/api/v2/info?fileUrl=https://pdf.ninja/demo.pdf&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me
Response
{"success": true, "title": "...", "subject": "...", "keywords": "...", "authors": ["...", "..."], "creator": "...", "producer": "...", "creationDate": "...", "modificationDate": "...", "pdfVersion": "...", "pages": [ {"number": 1, "width": "...", "height": "...", "sizeUnits": "pts"}, "..." ], "fields": [ {"type": "text|radio|select|checkbox", "name": "...", "alt": "...", "options": ["...", "..."], "flags": ["...", "..."]}, "..." ]}

If the fileId argument is used and the file cache has expired, "noSuchFileId" reason is returned.

{"success": false, "error": "no file with such file id", "reason": "noSuchFileId"}

If the md5sum argument does not match the md5 sum of the file contents, "md5sumMismatch" reason is returned.

{"success": false, "error": "MD5 sum mismatch", "reason": "md5sumMismatch"}

GET /api/v2/fields

Parameters

Returns fields available in a PDF file.

Request
$ curl "https://pdf.ninja/api/v2/fields?fileId=test&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me $ curl "https://pdf.ninja/api/v2/fields?fileUrl=https://pdf.ninja/demo.pdf&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me
Response
{"success": true, "fields": [ {"type": "text|radio|select|checkbox", "name": "...", "alt": "...", "options": ["...", "..."], "flags": ["...", "..."]}, "..." ]}

If the fileId argument is used and the file cache has expired, "noSuchFileId" reason is returned.

{"success": false, "error": "no file with such file id", "reason": "noSuchFileId"}

If the md5sum argument does not match the md5 sum of the file contents, "md5sumMismatch" reason is returned.

{"success": false, "error": "MD5 sum mismatch", "reason": "md5sumMismatch"}
Field Flags

Fields have common and type specific flags documented below,

Type Name Meaning
* ReadOnly The user may not change the value of the field.
* Required The field must have a value at the time it is exported by a submit-form action.
* NoExport The field must not be exported by a submit-form action.
text Multiline The field may contain multiple lines of text.
text Password The field is intended for entering a secure password that should not be echoed visibly to the screen.
text FileSelect The text entered in the field represents the pathname of a file whose contents are to be submitted as the value of the field.
text, select DoNotSpellCheck The text entered in the field will not be spell-checked.
text DoNotScroll The field will not scroll (horizontally for single-line fields, vertically for multiple-line fields) to accommodate more text than will fit within its annotation rectangle. Once the field is full, no further text will be accepted.
radio NoToggleToOff Exactly one radio button must be selected at all times.
select Combo The field is a combo box. If this flag is not set, the field is a list box.
select Edit The combo box includes an editable text box as well as a drop list; if this flag is not set, it includes only a drop list. This flag is meaningful only if the Combo flag is set.
select Sort The field's option items should be sorted alphabetically.
select MultiSelect More than one of the field's option items may be selected simultaneously.

POST /api/v2/fill

Parameters

Fills fields in the PDF file and returns a temporary URL to the output PDF file.

Request
$ curl -X POST "https://pdf.ninja/api/v2/fill" -F 'data={"Name":"John","Address":"My address"}' -F "fileId=test" -F "md5sum=022cb6201da97ab7b745f88978d4cab7" -F "key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me $ curl -X POST "https://pdf.ninja/api/v2/fill" --data "data=%7B%22Name%22%3A%22John%22%2C%22Address%22%3A%22My address%22%7D&fileUrl=https://pdf.ninja/demo.pdf&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me
Response
{"success": true, "fileUrl": "https://..."}

If the fileId argument is used and the file cache has expired, "noSuchFileId" reason is returned.

{"success": false, "error": "no file with such file id", "reason": "noSuchFileId"}

If the md5sum argument does not match the md5 sum of the file contents, "md5sumMismatch" reason is returned.

{"success": false, "error": "MD5 sum mismatch", "reason": "md5sumMismatch"}

If the field doesn't exist in the PDF file, an error message is returned.

{"success": false, "error": "Field 'Name' does not exist"}

GET /api/v2/image

Parameters

Converts PDF file to an image and returns a temporary URL to the output image file.

Supported output image formats: jpeg, png, svg, pdf, webp, tiff, bmp

Request
$ curl "https://pdf.ninja/api/v2/image?fileId=test&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me $ curl "https://pdf.ninja/api/v2/image?fileUrl=https://pdf.ninja/demo.pdf&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me
Response
{"success": true, "fileUrl": "https://..."}

If the fileId argument is used and the file cache has expired, "noSuchFileId" reason is returned.

{"success": false, "error": "no file with such file id", "reason": "noSuchFileId"}

If the md5sum argument does not match the md5 sum of the file contents, "md5sumMismatch" reason is returned.

{"success": false, "error": "MD5 sum mismatch", "reason": "md5sumMismatch"}

POST /api/v2/embed

Parameters

Embeds images into the specified pages and at the specified locations with the specified sizes and returns a temporary URL to the output PDF file. If page is not specified, the image is added at the center of every page. If location is not specified, the image is added in the center of the page. If size is not specified, the image is scaled to fill the page. If no embeds attributes are specified for a submitted image, defaults will be used.

Supported input image formats: jpeg, png, gif, tiff, bmp, svg, pdf, webp

Request
$ curl "https://pdf.ninja/api/v2/embed" -F images[1]=@embed.png -F 'embeds=[{"image":1,"page":1,"left":10,"top":10,"width":50,"height":50},{"image":1,"page":1,"left":70,"top":10,"width":50,"height":50}]' -F "fileId=test" -F "md5sum=022cb6201da97ab7b745f88978d4cab7" -F "key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Try me
$ curl "https://pdf.ninja/api/v2/embed" -F images[1]=@embed.png -F "fileUrl=https://pdf.ninja/demo.pdf" -F "md5sum=022cb6201da97ab7b745f88978d4cab7" -F "key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Try me
Response
{"success": true, "fileUrl": "https://..."}

If the fileId argument is used and the file cache has expired, "noSuchFileId" reason is returned.

{"success": false, "error": "no file with such file id", "reason": "noSuchFileId"}

If the md5sum argument does not match the md5 sum of the file contents, "md5sumMismatch" reason is returned.

{"success": false, "error": "MD5 sum mismatch", "reason": "md5sumMismatch"}

POST /api/v2/fillembed

Parameters

Combines fill and embed features into a single action.

Request
$ curl "https://pdf.ninja/api/v2/fillembed" -F 'data={"Name":"John","Address":"My address"}' -F images[1]=@embed.png -F 'embeds=[{"image":1,"page":1,"left":10,"top":10,"width":50,"height":50},{"image":1,"page":1,"left":70,"top":10,"width":50,"height":50}]' -F "fileId=test" -F "md5sum=022cb6201da97ab7b745f88978d4cab7" -F "key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Try me
$ curl "https://pdf.ninja/api/v2/fillembed" -F 'data={"Name":"John","Address":"My address"}' -F images[1]=@embed.png -F 'embeds=[{"image":1,"page":1,"left":10,"top":10,"width":50,"height":50},{"image":1,"page":1,"left":70,"top":10,"width":50,"height":50}]' -F "fileUrl=https://pdf.ninja/demo.pdf" -F "md5sum=022cb6201da97ab7b745f88978d4cab7" -F "key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Try me
Response
{"success": true, "fileUrl": "https://..."}

If the fileId argument is used and the file cache has expired, "noSuchFileId" reason is returned.

{"success": false, "error": "no file with such file id", "reason": "noSuchFileId"}

If the md5sum argument does not match the md5 sum of the file contents, "md5sumMismatch" reason is returned.

{"success": false, "error": "MD5 sum mismatch", "reason": "md5sumMismatch"}

GET /api/v2/capabilities

Parameters

Returns API capabilities.

Request
$ curl "https://pdf.ninja/api/v2/capabilities" Try me
Response
{"success": true, "features": []}

Privacy Policy

Your privacy and data security is our top priority. The API infrastructure is hosted in a secure environment. Communication between the API and user infrastructure is always encrypted via TLS. The generated PDFs are deleted on the server after a few minutes. Blank (original) PDFs are cached on the server for a week. Request data and responses are logged for debugging purposes and are deleted after a month. Generated PDF files are randomly reviewed to ensure proper API operation and to detect bugs. Some data submitted to the API (for example, data that causes API errors) may, with user permission, be kept indefinitely and incorporated into our test suite to improve quality of our software. All other user data is eventually deleted from all systems after about one month. Contact us for more information.