Legacy Pdfcrowd API v1

This is the documentation for the legacy Pdfcrowd API v1. We strongly recommend the new improved Pdfcrowd API v2 for new integrations.

API v1 Client Libraries Documentation & Downloads

REST API v1 Documentation

An API call is made by sending an HTTP request to the API endpoint with parameters passed as POST data. The API endpoints support both http and https schemes.

Authentication

The following parameters are used for authentication and must be present in every API call.

PDF Creation

A PDF document can be created in one of the following ways. The created PDF is returned in the response body.

Common Parameters

The following optional parameters control properties of the generated PDF file.

Page Setup

Some parameters can be specified in inches (in), millimeters (mm), centimeters (cm), or points (pt). If no units are specified, points are assumed.

Examples: 210mm, 8.5in

Header and Footer

HTML options

PDF Options

Watermark

Miscellaneous

Examples of API calls

The following command converts www.google.com to PDF:

$ curl -F "username=$username" -F "key=$apikey" \
>      -F 'src=http://www.google.com' \
>      http://pdfcrowd.com/api/pdf/convert/uri/ > google_com.pdf

The following command converts the output of some html_producer application to PDF and protects it with an user password:

$ html_producer | curl -F "username=$username" -F "key=$apikey" \
>                      -F 'src=<-' \
>                      -F 'user_pwd=secret' \
>                      http://pdfcrowd.com/api/pdf/convert/html/ > google_com.pdf

The following command converts a local file index.html to PDF and disables printing:

$ curl -F "username=$username" -F "key=$apikey" \
>      -F 'src=@index.html' \
>      -F 'no_print=1' \
>      http://pdfcrowd.com/api/pdf/convert/html/ > google_com.pdf

Note, that the examples above ignore errors. If the API call fails google_com.pdf will contain an error message instead of PDF. For convenience, Pdfcrowd provides a shell wrapper around curl that checks for errors and generally makes the interaction with the API from the command line friendlier.

User Status

The response contains the result in plain text.

$ curl -F "username=$username" -F "key=$apikey" \
>      "http://pdfcrowd.com/api/user/$username/tokens/"
$ 12399

Return Codes

The API returns the standard HTTP response status codes. These are the most important ones:

Shell

Pdfcrowd provides a shell script which wraps curl and provides more convenient access to the API from shell.

The script reads options from ~/.pdfcrowd and then from the command line. You can store your default options to ~/.pdfcrowd, one option per line:

$ cat > ~/.pdfcrowd <<!
> -username $username
> -key $apikey
> -width 210mm
> -height 297mm
> !

Now, you can run:

$ pdfcrowd.sh http://www.google.com > google_com.pdf
$ pdfcrowd.sh /path/to/local/file > html.pdf
$ html_producer | pdfcrowd.sh - > file.pdf
$ echo "remaining credits: $(pdfcrowd.sh @)"

On success, exit status 0 is returned and the result is written to stdout. Otherwise, non-zero exit status is returned and the error message is written to stderr. Run the script with -help to get the list of available options.

Data Security

We understand that your data may be sensitive and confidential and that it is absolutely unacceptable to disclose it or keep unnecessary copies.

We want to be transparent about how we process your data, so here we describe an API conversion request lifecycle:

1. Your request hits our HTTP server. Depending on the method you use:
   • Any data uploaded with convertHtml or convertFile is temporarily saved to a directory (dirA/) on our server.
   • Any other data is downloaded directly by the user agent during the conversion. The user agent has caching disabled.
2. Our backend process creates a PDF from your data and saves it temporarily to a directory (dirB/) on our server.
3. The HTTP server streams the created PDF from dirB/ back to you.
4. Both dirA/ and dirB/ are scanned every 10 minutes by a script which deletes the old files.

API Limitations

The following limits are applied to ensure fair distribution of capacity.

If you find the limits too restrictive we can provision a private server optimized for your specific needs with the limits lifted. If you would like to discuss this option please contact us.

Rate Limiting

The API returns an HTTP 503 Service unavailable status code in the following cases:

• The client sends more than 30 requests per minute from a single IP. Note, that a query on the number of credits counts against the limit.
• The client sends more than one simultaneous request from a single IP at a time.

  Ideally, you should serialize your API calls. However, we understand that you can't always ensure this in some environments, such as for instance with Google App Engine Task Queue. In such cases it is perfectly acceptable to check for this error and possibly send the failed request again.

Time Limit

If a request takes more than 40 seconds to complete it is cancelled and either of these messages may be returned:

• 510 - 413 Timed out. Can't load the specified URL.
• 502 - Sorry, we couldn't process your request.

A typical cause of this error is too many images on an HTML page which take too long to download. Another cause might be a long running JavaScript.

Size Limits

If the size of the uploaded data exceeds 20MB then an HTTP 413 Request entity too large error is returned. You can zip your HTML to avoid this error.

If the size of the downloaded data exceeds 100MB then the an HTTP 502 error code is returned.

Miscellaneous

We return an HTTP 502 error code also when:

• The converted page loads more than 2,000 sub-resources (images, external stylesheets, etc.)
• There is more than 8 HTTP redirects when attempting to load a page sub-resource.