Getting started with the PDF Blocks API

The PDF Blocks API accepts multipart/form-data requests, returns application/pdf responses, and uses standard HTTP response codes.

Base URL

The default global base URL is https://api.pdfblocks.com/

If you want your documents processed only in servers located in the European Union use https://eu.api.pdfblocks.com/

Authentication

The PDF Blocks API uses API keys to authenticate requests. You can view and manage your API keys in your dashboard.

Authentication to the API is performed via the X-Api-Key header. For example in curl:

curl \
https://api.pdfblocks.com/v1/add_password \
-H 'X-Api-Key: 0123456789abcdef0123456789abcdef' \
# ...

Do all API requests over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Versioning

The PDF Blocks API uses Semantic Versioning v2.0.0:

We increment Major (X.Y.Z) versions when we make a change that breaks backward compatibility. The current major version is 1.
We increment Minor (X.Y.Z) versions when we add backward compatible features.
We increment Patch (X.Y.Z) versions when we make backward compatible bug fixes.

Examples of backward compatible changes:

Add a new optional parameter.
Allow more values in a parameter (eg add more colors to text watermarks).
Rename a parameter or endpoint keeping the old name as an alias.
Add extra headers or attributes to a response.

Before deploying each new version, we do extensive regression tests on our API. Contact us if you want us to include any critical step in your workflow in our regression test suite (only for paying customers).

Hyrum’s Law mitigation

Every API change —even backward-compatible bug fixes— may be a failure dependency for someone (see Hyrum’s Law or xkcd). To mitigate this, we can set up a private PDF server with the X.Y.Z version of your choosing. Contact us if you are interested.

Errors

PDF Blocks uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an input document is invalid, etc.). Codes in the 5xx range indicate an error with PDF Blocks’ servers (these are rare).

Most errors provide a RFC 7807 problem detail with Content-Type: application/problem+json, and the following attributes.

Problem detail attributes

type string

A URL with human-readable documentation about the problem type.

title string

A short, human-readable summary of the problem type.

status integer

The HTTP status code for this occurrence of the problem.

errors dictionary

For validation errors, a dictionary of field names → array of error messages.

Problem detail example

{
    "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "file": [
            "Could not parse the PDF document. The file may be invalid or corrupt."
        ]
    }
}