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.
The default global base URL is
If you want your documents processed only in servers located in the European Union use
You can also self-host your own PDF Blocks server and set your own base URL.
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:
Do all API requests over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
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
- 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.
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).
Problem detail attributes
A URL with human-readable documentation about the problem type.
A short, human-readable summary of the problem type.
The HTTP status code for this occurrence of the problem.
For validation errors, a dictionary of field names → array of error messages.