Document Alchemy API Version 1.3.3Interactive API Reference

 

Document Alchemy is a robust web service for reading, writing, processing and transforming documents in many formats, including:

  • Microsoft Word, Excel and PowerPoint
  • Apache OpenOffice Writer, Calc and Impress.
  • the Portable Document Format (PDF; Adobe Acrobat)
  • HTML, Markdown and other text formats
  • PNG, JPEG, GIF and WebP images

and many others.

The content below is both a reference for and demonstration of the DocumentAlchemy API.

You can use this page as online documentation of the DocumentAlchemy API—it contains detailed information on the various API methods, their inputs, outputs and parameters.

You can also use this page to experiment with the DocumentAlchemy API directly from your browser.

To use this page interactively:

  1. If you haven't already, sign up for a DocumentAlchemy account to immediately get your own API Key.
  2. Enter or select your DocumentAlchemy API Key in the field provided in the upper-right.
  3. Expand any of the API method descriptions below.
  4. Provide API parameter values as needed.
  5. Click “Submit Live Request” to invoke the API method.

The server's response to your request will appear, together the details of the request that was submitted.

A history of changes to this API can be found here. A Swagger-format (OpenAPI-format) description of this API can be found here.

If you have any questions, comments or suggestions regarding the DocumentAlchemy API, please contact us.

The content below is a reference for the DocumentAlchemy API.

You can find the latest version of this documentation at https://documentalchemy.com/api-doc.

The online documentation also serves as an interactive tool for exploring the API.

A history of changes to this API can be found at https://documentalchmey.com/api-version-history.

A Swagger-format (OpenAPI-format) description of this API can be found at https://documentalchemy.com/apid/v1/swagger.json.

If you have any questions, comments or suggestions regarding the DocumentAlchemy API, please contact us at https://documentalchemy.com/contact-us.

 

Document Processing Generic Conversion and Rendering 

GET/document/{doc_id}/rendition/{format}
Render a previously stored document in the specified format.
 

Description

The GET /document/{id}/rendition/{format} endpoint (and the corresponding "inline data" version POST /document/-/rendition/{format}) POST /document/-/rendition/{format}) is the central method of the DocumentAlchemy API. Most DocumentAlchemy API endpoints are variations on this theme. In fact, you may notice that many of the endpoints documented under Type-specific Specializations are really just a special cases of these method. We've covered those methods independently in order to call attention to parameters or constraints that are only relevant to that special case.

This endpoint generates and returns (or stores) a "converted" version of the specified document as determined by the format parameter.

The range of acceptable output formats is in part determined by the type (format) of the input document. Individual limitations or constraints are discussed within the documentation of the special-case variations on this method, but note that we are continually expanding the number and variety of transformation and conversions that DocumentAlchemy supports. That is, if we currently do not support a transformation from Type X to Type Y, know that are interested in and quite possibly actively working on adding that capability. (If we're missing a transformation that is particularly important to you, please let us know, we love to hear from you.)

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the following demonstrations for live examples of this functionality:

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/rendition/{format}

Produces

application/json
application/octet-stream

Parameters

doc_id

required, string, path

Identifier for the (previously stored) document to be rendered.

format

required, string, path

Format or type of rendition to return, e.g. pdf or docx.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the rendition is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the rendition has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/-/rendition/{format}
Render an uploaded document in the specified format.
 

Description

The POST /document/-/rendition/{format} endpoint (and the corresponding "stored document" version GET /document/{id}/rendition/{format}) is the central method of the DocumentAlchemy API. Most DocumentAlchemy API endpoints are variations on this theme. In fact, you may notice that many of the endpoints documented under Type-specific Specializations are really just a special cases of these method. We've covered those methods independently in order to call attention to parameters or constraints that are only relevant to that special case.

This endpoint generates and returns (or stores) a "converted" version of the uploaded document as determined by the format parameter.

The range of acceptable output formats is in part determined by the type (format) of the input document. Individual limitations or constraints are discussed within the documentation of the special-case variations on this method, but note that we are continually expanding the number and variety of transformation and conversions that DocumentAlchemy supports. That is, if we currently do not support a transformation from Type X to Type Y, know that are interested in and quite possibly actively working on adding that capability. (If we're missing a transformation that is particularly important to you, please let us know, we love to hear from you.)

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the following demonstrations for live examples of this functionality:

Full Resource URL

https://documentalchemy.com/api/v1/document/-/rendition/{format}

Produces

application/json
application/octet-stream

Parameters

document

required, file, formData

Document to be rendered.

  Choose a File...  

format

required, string, path

Format or type of rendition to return, e.g. pdf or docx.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the rendition is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the rendition has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

Document Store Temporary File Store 

POST/document
Store a document for future processing or retrieval.
 

Description

Saves the given document or file into the DocumentAlchemy repository for future processing, returning a document identifier that can be used to retrieve, modify, delete or process the document.

A stored document can only be accessed, modified, deleted or processed by the API client that created it. (The corresponding API client is identified by the client's API Key, but is independent of the specific API key value. Hence you can regenerate the "secret key" value associated with an API client without losing access to the documents stored with the previous value.)

The document store is intended to provide a form of "working memory" and to avoid the need to upload the same document multiple times in a short period. It is not intended to provide durable or long-term storage.

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

Full Resource URL

https://documentalchemy.com/api/v1/document

Produces

application/json

Parameters

document

required, file, formData

File to be stored.

  Choose a File...  

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

201

An HTTP 201 response indicates that the document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/document/{doc_id}
Fetch a previously stored document.
 

Description

Returns the specified document.

A stored document can only be accessed, modified, deleted or processed by the API client that created it. (The corresponding API client is identified by the client's API Key, but is independent of the specific API key value. Hence you can regenerate the "secret key" value associated with an API client without losing access to the documents stored with the previous value.)

When rm=true is passed as a query string parameter, the underlying file will be deleted as soon as it is returned.

This method will return an HTTP 404 response:

  • if the specified file is not found,
  • if the file has expired (based on the ttl value it was stored with)
  • if the file exists but is not accessible to the current API client.

(Hence if you are using the wrong API key, this method will return a 404 response, not a 403. This is to prevent attempts to "guess" at document identifiers.)

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}

Produces

application/octet-stream

Parameters

doc_id

required, string, path

Identifier for the (previously stored) document to be returned.

rm

optional, boolean, query

When true, the file will be deleted after it is returned. Defaults to false.

 
 

Standard Responses

200

Success! The requested document can be found in the response body.

Error Responses...

PUT/document/{doc_id}
Replace (overwrite) a previously stored document.
 

Description

Replaces a currently stored the given document with the uploaded file.

A stored document can only be accessed, modified, deleted or processed by the API client that created it. (The corresponding API client is identified by the client's API Key, but is independent of the specific API key value. Hence you can regenerate the "secret key" value associated with an API client without losing access to the documents stored with the previous value.)

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}

Parameters

document

required, file, formData

File to be stored.

  Choose a File...  

doc_id

required, string, path

Identifier for the (previously stored) document to be replaced.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

204

An HTTP 204 response indicates that the document has been stored and can be accessed using the pre-existing document identifier.

Error Responses...

DELETE/document/{doc_id}
Delete a previously stored document.
 

Description

Removes the specified document from the document store.

A stored document can only be accessed, modified, deleted or processed by the API client that created it. (The corresponding API client is identified by the client's API Key, but is independent of the specific API key value. Hence you can regenerate the "secret key" value associated with an API client without losing access to the documents stored with the previous value.)

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}

Parameters

doc_id

required, string, path

Identifier for the (previously stored) document to be deleted.

 
 

Standard Responses

204

An HTTP 204 response indicates that the document has been removed.

Error Responses...

Type-specific Specializations Special Cases of Document Processing 

GET/document/-/rendition/{format}
Render a web page (URL) as an image.
 

Description

Generates and returns (or stores) a "screenshot" of the web page at the given URL as a PNG or JPEG image.

The url parameter specifies the URL of the document to be rendered. The URL must start with http:// or https://. Like any query string parameter, reserved characters in the the url value should be "Percent-Encoded" (URL-encoded) as described in Section 2 of RFC 3986. (For example, if your original URL is http://example.com/food?q=pork+&26+beans the url query string parameter might be written ?url=http%3A%2F%2Fexample.com%2Ffood%3Fq%3Dpork%2B%2626%2Bbeans)

The format value found in the API method's path indicates the type of image to generate. Currently must be either png or jpg.

The size and shape of the generated image are determined by the following query string parameters.

  • bw and bh ("Browser Width" and "Browser Height") specify the width and height (in pixels) of the "viewport" of the web browser window when the image is captured.
    • When bw is omitted it assumes the default value of 1024.
    • When bh is omitted (or 0), the "full" height of the specified web page will be captured. In other words, the browser window will be automatically sized to be tall enought to contain the full content of the page.
  • iw and ih ("Image Width" and "Image Height") specify the width and height (in pixels) of the generated image.
    • When both iw and ih are ommitted (or both 0), the generated image will the be same size as the browser window.
    • When iw is specified but ih if ommitted (or 0), the generated image will be scaled to be iw pixels wide while preserving the original image's aspect ratio.
    • When ih is specified but iw if ommitted (or 0), the generated image will be scaled to be ih pixels tall while preserving the original image's aspect ratio.
    • When both iw and ih are specified, the image will be scaled down until it fits entirely within the specified width and height. (Note that unless iw and ih have the same aspect ratio as bw and bh, the returned image will be less than but not exactly iw × ih pixels. In the general case only one of the two dimensions will be the exact value that is specified, the other will be smaller.)
  • When ei ("Enlarge Image") is true, the image will be scaled up to the largest size that still fits within the specified iw and ih values. When false, the image will never be enlarged — the image will only be re-scaled if original image is larger than the desired size. When omitted, ei defaults to false.

The header parameter may be used to specify HTTP headers that will be submitted along with the request to fetch the web page (and associated assets like images and scripts). The header value should be in the form <name>:<value>.

The header parameter may be repeated in order to submit multiple headers. (For example, ?header=Cookie:name=value&header=DNT:1.)

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

Full Resource URL

https://documentalchemy.com/api/v1/document/-/rendition/{format}

Produces

application/json
image/png
image/jpeg

Parameters

url

required, string, query

The URL of the document to be rendered. This URL MUST start with http:// or https://.

format

required, string, path

Image Format
Accepts: png, jpg

bw

optional, integer, query

Width of the browser window when capturing the "screenshot", in pixels. Defaults to 1024. (See description for details.)
(value >= 0)

bh

optional, integer, query

Height of the browser window when capturing the "screenshot", in pixels. Defaults to 0, indicating that the browser window should be tall enough to contain all of the web page's content. (See description for details.)
(value >= 0)

iw

optional, integer, query

Desired width of the generated image, in pixels. (See description for details.)
(value >= 0)

ih

optional, integer, query

Desired height of the generated image, in pixels. (See description for details.)
(value >= 0)

ei

optional, string, query

When true the image may be enlarged to fill the desired width and height. Otherwise the original image will not be resized if already fits within the box specified by iw and ih. (See description for details.)
Accepts: true, ``

header

optional, string, query

HTTP header to submit with the request. May be repeated. (See description for details.)

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the rendition is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the rendition has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/document/{doc_id}/rendition/docx
Render a previously-stored Markdown document as an MS Word document.
 

Description

A Markdown-to-MS Word-specific version of the GET /document/{doc_id}/rendition/{format} endpoint.

This endpoint generates an MS Word rendition of the stored Markdown document.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the Markdown to Word demonstration for another live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/rendition/docx

Produces

application/json
application/vnd.openxmlformats-officedocument.wordprocessingml.document

Parameters

doc_id

required, string, path

Identifier for the (previously stored) document to be rendered.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated MS Word document is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated MS Word document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/-/rendition/docx
Render an uploaded Markdown document as an MS Word document.
 

Description

A Markdown-to-MS Word-specific version of the POST /document/-/rendition/{format} endpoint.

This endpoint generates an MS Word rendition of the uploaded Markdown document.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the Markdown to Word demonstration for another live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/-/rendition/docx

Produces

application/json
application/vnd.openxmlformats-officedocument.wordprocessingml.document

Parameters

document

required, file, formData

Markdown document to be rendered.

  Choose a File...  

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated MS Word document is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated {output_type} document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/document/{doc_id}/rendition/html
Render a previously-stored Markdown document as an HTML document.
 

Description

A Markdown-to-HTML-specific version of the GET /document/{doc_id}/rendition/{format} endpoint.

This endpoint generates an HTML rendition of the stored Markdown document.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the Markdown to HTML demonstration for another live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/rendition/html

Produces

application/json
text/html

Parameters

doc_id

required, string, path

Identifier for the (previously stored) document to be rendered.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated HTML document is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated HTML document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/-/rendition/html
Render an uploaded Markdown document as an HTML document.
 

Description

A Markdown-to-HTML-specific version of the POST /document/-/rendition/{format} endpoint.

This endpoint generates an HTML rendition of the uploaded Markdown document.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the Markdown to HTML demonstration for another live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/-/rendition/html

Produces

application/json
text/html

Parameters

document

required, file, formData

Markdown document to be rendered.

  Choose a File...  

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated HTML document is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated {output_type} document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/document/{doc_id}/rendition/md
Render a previously-stored MS Word document as a Markdown file.
 

Description

A Word-to-Markdown-specific version of the GET /document/{doc_id}/rendition/{format} endpoint.

This endpoint generates a Markdown rendition of the stored Microsoft Word document.

By default this method will generate a Markdown document. When the query string parameter media is set to true, this method will generate a ZIP file containing both the Markdown document and a media directory containing all images extracted from the Word document.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the Word to Markdown demonstration for another live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/rendition/md

Produces

application/json
text/markdown
application/zip

Parameters

doc_id

required, string, path

Identifier for the (previously stored) document to be rendered.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

media

optional, string, query

When true, multimedia content stored in the MS Word document will be included in the response. The returned object will be a ZIP archive containing both the Markdown document and associated media files. Defaults to false.
Accepts: true, false

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated Markdown document (or ZIP-file) is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated Markdown document (or ZIP-file) has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/-/rendition/md
Render an uploaded MS Word document as a Markdown file.
 

Description

A Word-to-Markdown-specific version of the POST /document/-/rendition/{format} endpoint.

This endpoint generates a Markdown rendition of the uploaded Microsoft Word document.

By default this method will generate a Markdown document. When the query string parameter media is set to true, this method will generate a ZIP file containing both the Markdown document and a media directory containing all images extracted from the Word document.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the Word to Markdown demonstration for another live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/-/rendition/md

Produces

application/json
text/markdown
application/zip

Parameters

document

required, file, formData

MS Word document to be rendered.

  Choose a File...  

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

media

optional, string, query

When true, multimedia content stored in the MS Word document will be included in the response. The returned object will be a ZIP archive containing both the Markdown document and associated media files. Defaults to false.
Accepts: true, false

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated Markdown document (or ZIP-file) is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated Markdown document (or ZIP-file) has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/document/{doc_id}/rendition/pdf
Render a previously-stored MS Office document as a PDF document.
 

Description

A MS Office-to-PDF-specific version of the GET /document/{doc_id}/rendition/{format} endpoint.

This endpoint generates a PDF rendition of the stored MS Office document.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the Word to PDF demonstration, Excel to PDF demonstration and PowerPoint to PDF demonstration for additional live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/rendition/pdf

Produces

application/json
application/pdf

Parameters

doc_id

required, string, path

Identifier for the (previously stored) document to be rendered.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated PDF document is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated PDF document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/document/{doc_id}/rendition/pdf
Render a previously-stored Markdown document as a PDF document.
 

Description

A Markdown-to-PDF-specific version of the GET /document/{doc_id}/rendition/{format} endpoint.

This endpoint generates a PDF rendition of the stored Markdown document.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the Markdown to PDF demonstration for another live examples of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/rendition/pdf

Produces

application/json
application/pdf

Parameters

doc_id

required, string, path

Identifier for the (previously stored) document to be rendered.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

margin

optional, string, query

Margin to use in generated PDF, such as 30mm or 0.5in. Defaults to 1in.

papersize

optional, string, query

Size of paper for the generated PDF document. Defaults to letter.
Accepts: letter, a4

numberpages

optional, string, query

When true, add page numbers to the generated PDF document. Defaults to false
Accepts: true, false

firstpagespecial

optional, string, query

When true, the page number will not be printed on the first page. Defaults to false
Accepts: true, false

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated PDF document is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated PDF document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/-/rendition/pdf
Render an uploaded MS Office document as a PDF document.
 

Description

A MS Office-to-PDF-specific version of the POST /document/-/rendition/{format} endpoint.

This endpoint generates a PDF rendition of the uploaded MS Office document.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the Word to PDF demonstration, Excel to PDF demonstration and PowerPoint to PDF demonstration for additional live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/-/rendition/pdf

Produces

application/json
application/pdf

Parameters

document

required, file, formData

MS Office document to be rendered.

  Choose a File...  

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated PDF document is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated {output_type} document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/-/rendition/pdf
Render an uploaded Markdown document as a PDF document.
 

Description

A Markdown-to-PDF-specific version of the POST /document/-/rendition/{format} endpoint.

This endpoint generates a PDF rendition of the uploaded Markdown document.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the Markdown to PDF demonstration for another live examples of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/-/rendition/pdf

Produces

application/json
application/pdf

Parameters

document

required, file, formData

Markdown document to be rendered.

  Choose a File...  

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

margin

optional, string, query

Margin to use in generated PDF, such as 30mm or 0.5in. Defaults to 1in.

papersize

optional, string, query

Size of paper for the generated PDF document. Defaults to letter.
Accepts: letter, a4

numberpages

optional, string, query

When true, add page numbers to the generated PDF document. Defaults to false
Accepts: true, false

firstpagespecial

optional, string, query

When true, the page number will not be printed on the first page. Defaults to false
Accepts: true, false

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated PDF document is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated PDF document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/document/{doc_id}/rendition/media.zip
Extract media (images) from a previously stored MS Office or PDF document.
 

Description

The special media.zip rendition type is used to obtain an archive containing all images embedded within the source document.

Currently Microsoft Office (.doc, .docx, .xls, .xlsx, .ppt, .pptx, etc.) and PDF documents are supported.

The generated archive will contain a single directory, named media. All extracted media files will be contained within that media directory.

An empty media directory indicates that no images could be extracted from the source document.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/rendition/media.zip

Produces

application/json
application/zip

Parameters

doc_id

required, string, path

Identifier for the (previously stored) document to be rendered.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated media archive is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated media archive has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/-/rendition/media.zip
Extract media (images) from an uploaded MS Office or PDF document.
 

Description

The special media.zip rendition type is used to obtain an archive containing all images embedded within the source document.

Currently Microsoft Office (.doc, .docx, .xls, .xlsx, .ppt, .pptx, etc.) and PDF documents are supported.

The generated archive will contain a single directory, named media. All extracted media files will be contained within that media directory.

An empty media directory indicates that no images could be extracted from the source document.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

Full Resource URL

https://documentalchemy.com/api/v1/document/-/rendition/media.zip

Produces

application/json
application/zip

Parameters

document

required, file, formData

Microsoft Office or PDF document from which media will be extracted.

  Choose a File...  

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated media archive is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated media archive has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/document/{doc_id}/rendition/wordcount.json
Count the number of words in a previously stored MS Office or PDF document.
 

Description

The special wordcount.json rendition type is used to obtain a simple JSON document containing the number words found in the input document.

Currently Microsoft Office (.doc, .docx, .xls, .xlsx, .ppt, .pptx, etc.) and PDF documents are supported.

The generated JSON document will contain wordcount attribute mapping to the number of words found in the input document.

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/rendition/wordcount.json

Produces

application/json

Parameters

doc_id

required, string, path

Identifier for the (previously stored) document to be rendered.

 
 

Standard Responses

200

An HTTP 200 response indicates that the generated JSON document is available in the response body.

Error Responses...

POST/document/-/rendition/wordcount.json
Count the number of words in an uploaded MS Office or PDF document.
 

Description

The special wordcount.json rendition type is used to obtain a simple JSON document containing the number words found in the input document.

Currently Microsoft Office (.doc, .docx, .xls, .xlsx, .ppt, .pptx, etc.) and PDF documents are supported.

The generated JSON document will contain wordcount attribute mapping to the number of words found in the input document.

Full Resource URL

https://documentalchemy.com/api/v1/document/-/rendition/wordcount.json

Produces

application/json

Parameters

document

required, file, formData

Microsoft Office or PDF document to count the number of words in

  Choose a File...  
 
 

Standard Responses

200

An HTTP 200 response indicates that the generated JSON document is available in the response body.

Error Responses...

GET/document/{doc_id}/rendition/thumbnail.png
Create a thumbnail image for a previously stored document.
 

Description

Generates and returns (or stores) a thumbnail image representing the specified document.

The width and height parameters determine the size of the final thumbnail image, according to the following logic:

  • If both width and height are unspecified, or specified as 0, the resulting thumbnail image will be the "natural", full-size representation of the source document (but as a PNG image).

  • If both width and height are specified with non-zero values, the resulting thumbnail image will be scaled down (from its "natural", full size) until it fits within the specified pixel dimensions, respecting the original image's aspect ratio. (Note that the resulting image will be no more than width by height pixels, but it may be less in one or both dimensions depending upon the page-size and aspect ratio of the original document.)

  • If one of width and height is specified with a non-zero value and the other is unspecified (or 0), the resulting image will be scaled-down until the specified dimension matches the specified value, preserving the original image's aspect ratio. The size of the unspecified dimension will be determined by the original image's aspect ratio.

    E.g., if a 900x1200 pixel document is provided, setting width=90 and height=0 will yield a 90x120 pixel thumbnail. Setting width=0 and height=600 will yield a 450x600 pixel thumbnail.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the following demonstrations for live examples of this functionality:

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/rendition/thumbnail.png

Produces

application/json
application/octet-stream

Parameters

doc_id

required, string, path

Identifier for the (previously stored) document to be rendered.

width

optional, integer, query

The preferred width of the generated image in pixels. Defaults to 0. (See description for details.)
(value >= 0)

height

optional, integer, query

The preferred height of the generated image in pixels. Defaults to 0. (See description for details.)
(value >= 0)

page

optional, integer, query

The page of the the source document which should be used as the basis of the thumbnail. Defaults to 1. Will trigger an error if the specified page number is outside the bounds of the document.
(value >= 1)

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the thumbnail image is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the thumbnail image has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/-/rendition/thumbnail.png
Create a thumbnail image for an uploaded document.
 

Description

Generates and returns (or stores) a thumbnail image representing the specified document.

The width and height parameters determine the size of the final thumbnail image, according to the following logic:

  • If both width and height are unspecified, or specified as 0, the resulting thumbnail image will be the "natural", full-size representation of the source document (but as a PNG image).

  • If both width and height are specified with non-zero values, the resulting thumbnail image will be scaled down (from its "natural", full size) until it fits within the specified pixel dimensions, respecting the original image's aspect ratio. (Note that the resulting image will be no more than width by height pixels, but it may be less in one or both dimensions depending upon the page-size and aspect ratio of the original document.)

  • If one of width and height is specified with a non-zero value and the other is unspecified (or 0), the resulting image will be scaled-down until the specified dimension matches the specified value, preserving the original image's aspect ratio. The size of the unspecified dimension will be determined by the original image's aspect ratio.

    E.g., if a 900x1200 pixel document is provided, setting width=90 and height=0 will yield a 90x120 pixel thumbnail. Setting width=0 and height=600 will yield a 450x600 pixel thumbnail.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the following demonstrations for live examples of this functionality:

Full Resource URL

https://documentalchemy.com/api/v1/document/-/rendition/thumbnail.png

Produces

application/json
image/png

Parameters

document

required, file, formData

Document to be rendered.

  Choose a File...  

width

optional, integer, query

The preferred width of the generated image in pixels. Defaults to 0. (See description for details.)
(value >= 0)

height

optional, integer, query

The preferred height of the generated image in pixels. Defaults to 0. (See description for details.)
(value >= 0)

page

optional, integer, query

The page of the the source document which should be used as the basis of the thumbnail. Defaults to 1. Will trigger an error if the specified page number is outside the bounds of the document.
(value >= 1)

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the thumbnail image is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the thumbnail image has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/data/-/rendition/qr.png
Generate a QR code that encodes data from a query string parameter.
 

Description

Returns a PNG-format image encoding the given data as a QR Code.

All parameters other than data are optional.

The size parameter specifies the height and width of the (always square) image, in pixels. When missing, a 400-by-400 pixel image is generated.

The ecl parameter specifies the “error correction level” to use when generating the QR code. From highest to lowest level of error correction, value values are H, Q, M and L. When missing, the highest level of error correction (H) is used. Note that the volume of data that can be encoded in a QR code decreases as the level of error-correction increases.

Unless the border parameter is set to false, a thin (module-sized) border will be placed around the image.

The fg and bg parameters specify the foreground and background colors to use when generating the QR code image, respectively. Values may take the form of RRGGBB hex strings (e.g., FF0000) or rgb triplets (e.g., rgb(255,0,0)). When missing, the foreground color defaults to black (000000) and the background color defaults to white (FFFFFF). Note that QR code readers may have difficulty reading QR codes with inverse or low-contrast color schemes.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the “Generate a QR Code” demo for a live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/data/-/rendition/qr.png

Produces

image/png
application/json

Parameters

data

required, string, query

Data to be encoded in the QR Code.

size

optional, integer, query

Height and width of the image in pixels. Defaults to 400.
(1 <= value <= 4000)

ecl

optional, string, query

QR code “error correction level”. Defaults to the highest level of error correction (H).
Accepts: L, M, Q, H

border

optional, boolean, query

Unless false include a small background-colored border around the image.

fg

optional, string, query

Foreground color as a hex string (e.g., FF0000) or RGB triplet (e.g., rbg(255,0,0)). When missing, defaults to black.

bg

optional, string, query

Background color as a hex string (e.g., FF0000) or RGB triplet (e.g., rbg(255,0,0)). When missing, defaults to white.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the image is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the image has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/data/-/rendition/qr.png
Generate a QR code that encodes data from the request body.
 

Description

Returns a PNG-format image encoding the given data as a QR Code.

All parameters other than data are optional.

The size parameter specifies the height and width of the (always square) image, in pixels. When missing, a 400-by-400 pixel image is generated.

The ecl parameter specifies the “error correction level” to use when generating the QR code. From highest to lowest level of error correction, value values are H, Q, M and L. When missing, the highest level of error correction (H) is used. Note that the volume of data that can be encoded in a QR code decreases as the level of error-correction increases.

Unless the border parameter is set to false, a thin (module-sized) border will be placed around the image.

The fg and bg parameters specify the foreground and background colors to use when generating the QR code image, respectively. Values may take the form of RRGGBB hex strings (e.g., FF0000) or rgb triplets (e.g., rgb(255,0,0)). When missing, the foreground color defaults to black (000000) and the background color defaults to white (FFFFFF). Note that QR code readers may have difficulty reading QR codes with inverse or low-contrast color schemes.

When text/plain content is POSTed, the entire request body will be interpreted as the data to encode in the QR code. When application/json content is POSTed, the request body will be interpreted as a JSON object, and the value of the data attribute of that object will be used as the data to encode in the QR code.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the “Generate a QR Code” demo for a live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/data/-/rendition/qr.png

Produces

image/png
application/json

Parameters

data

required, string, body

Data to be encoded in the QR Code.

size

optional, integer, query

Height and width of the image in pixels. Defaults to 400.
(1 <= value <= 4000)

ecl

optional, string, query

QR code “error correction level”. Defaults to the highest level of error correction (H).
Accepts: L, M, Q, H

border

optional, boolean, query

Unless false include a small background-colored border around the image.

fg

optional, string, query

Foreground color as a hex string (e.g., FF0000) or RGB triplet (e.g., rbg(255,0,0)). When missing, defaults to black.

bg

optional, string, query

Background color as a hex string (e.g., FF0000) or RGB triplet (e.g., rbg(255,0,0)). When missing, defaults to white.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the image is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the image has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/document/{doc_id}/rendition/pages.zip
Split a (previously stored) document into a collection of single-page files.
 

Description

Generates and returns (or stores) a zip archive containing one file for each page in the specified document.

Currently this method only accepts (and returns) documents in the PDF format.

Within the archive, each file is named according to the pattern page-01.pdf, page-02.pdf, etc., with the minimal number of leading zeros to ensure that each file name is the same number of characters long. In other words, if the document contains fewer than 10 pages the files will be named page-1, page-2, etc.; if the document contains between 10 and 99 pages the files will be named page-01, page-02, etc.; if the document contains between 100 and 999 pages the files will be named page-001, page-002, etc.; and so on.

The optional range parameter specifies a range of pages to be included in the generated archive. When it is ommitted, all of the pages of the source document will be included.

The range parameter accepts a comma-delimited list of specifiers. Each specifier may have one of the following forms:

  • When a single integer is specified, the corresponding page in the PDF will be included. E.g., the value 3 indicates that the third page in the document should be included.

  • When a dash (hyphen) delimited pair of integers is specified, the corresponding range in the PDF will be included (inclusive of the endpoints). E.g., the value 3-5 indicates that pages 3, 4 and 5 should be included.

  • When the values even or odd are specified, the even or odd pages (respectively) in the PDF will be included. E.g., the value even indicates that pages 2, 4, 6, 8, etc. should be included.

  • The value last is resolved to the page number of the final page in the document. That is, when the value last is specified, the final page of the PDF will be included. last may also be used as the right-hand-side of range. E.g., the value 5-last indicates that page 5, 6, 7, etc. should be included, up to and including the final page of the document.

  • An expression of the form last-N (for a positive integer N) is resolved to the page number of the final page in the document minus the specified value. That is, in a 10 page document, the expression last-3 resolves to 7. This “modified” form of last may be used as a stand-alone page identifier, or as the left or right side of a range expression. For example, given a 10 page document, the expression last-8,last-6-last-2 indicates that pages 2, 4, 5, 6, 7 and 8 should be included.

  • An exclamation point (!) in front of a specifier indicates that the corresponding range of pages should be excluded from the generated archive. For example, the expression 1-5,!3-4 indicates that pages 1, 2 and 5 should be included in the archive, but not page 3 or 4.

  • If all the terms in the range parameter have an exclamation-point prefix, then any page not explicitly excluded will be included. For example, given a 10 page document, a range of !3 indicates that pages 1, 2, 4, 5, 6, 7, 8, 9 and 10 should be incldued (everything but 3). A range of !even,!3-5,!9 indicates that only pages 1 and 7 should be included (2, 4, 6, 8 and 10 are eliminated by !even, 3 and 5 are eliminated by !3-5 and 9 is eliminated by !9).

  • If both "inclusive" (without-!) and "exclusive" (with-!) terms are found in the range parameter, the exclusive terms are interpreted as exceptions to the inclusive terms. That is, a page will be included in the generated archive if and only if it appears in at least one inclusive term and it does not appear in any exclusive term. For example, the range value odd,!3 indicates that pages 1, 5, 7 and 9 should be included.

Note that page numbering starts at 1.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the “Split a PDF into pages” demo for a live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/rendition/pages.zip

Produces

application/zip
application/json

Parameters

doc_id

required, string, path

Identifier for the (previously stored) document to be rendered.

range

optional, string, query

Pages to include (or exclude) form the archive. E.g., 2,3-7,!4,10-last-3,last. See description for details.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the generated archive is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the generated archive has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/-/rendition/pages.zip
Split an uploaded document into a collection of single-page files.
 

Description

Generates and returns (or stores) a zip archive containing one file for each page in the specified document.

Currently this method only accepts (and returns) documents in the PDF format.

Within the archive, each file is named according to the pattern page-01.pdf, page-02.pdf, etc., with the minimal number of leading zeros to ensure that each file name is the same number of characters long. In other words, if the document contains fewer than 10 pages the files will be named page-1, page-2, etc.; if the document contains between 10 and 99 pages the files will be named page-01, page-02, etc.; if the document contains between 100 and 999 pages the files will be named page-001, page-002, etc.; and so on.

The optional range parameter specifies a range of pages to be included in the generated archive. When it is ommitted, all of the pages of the source document will be included.

The range parameter accepts a comma-delimited list of specifiers. Each specifier may have one of the following forms:

  • When a single integer is specified, the corresponding page in the PDF will be included. E.g., the value 3 indicates that the third page in the document should be included.

  • When a dash (hyphen) delimited pair of integers is specified, the corresponding range in the PDF will be included (inclusive of the endpoints). E.g., the value 3-5 indicates that pages 3, 4 and 5 should be included.

  • When the values even or odd are specified, the even or odd pages (respectively) in the PDF will be included. E.g., the value even indicates that pages 2, 4, 6, 8, etc. should be included.

  • The value last is resolved to the page number of the final page in the document. That is, when the value last is specified, the final page of the PDF will be included. last may also be used as the right-hand-side of range. E.g., the value 5-last indicates that page 5, 6, 7, etc. should be included, up to and including the final page of the document.

  • An expression of the form last-N (for a positive integer N) is resolved to the page number of the final page in the document minus the specified value. That is, in a 10 page document, the expression last-3 resolves to 7. This “modified” form of last may be used as a stand-alone page identifier, or as the left or right side of a range expression. For example, given a 10 page document, the expression last-8,last-6-last-2 indicates that pages 2, 4, 5, 6, 7 and 8 should be included.

  • An exclamation point (!) in front of a specifier indicates that the corresponding range of pages should be excluded from the generated archive. For example, the expression 1-5,!3-4 indicates that pages 1, 2 and 5 should be included in the archive, but not page 3 or 4.

  • If all the terms in the range parameter have an exclamation-point prefix, then any page not explicitly excluded will be included. For example, given a 10 page document, a range of !3 indicates that pages 1, 2, 4, 5, 6, 7, 8, 9 and 10 should be incldued (everything but 3). A range of !even,!3-5,!9 indicates that only pages 1 and 7 should be included (2, 4, 6, 8 and 10 are eliminated by !even, 3 and 5 are eliminated by !3-5 and 9 is eliminated by !9).

  • If both "inclusive" (without-!) and "exclusive" (with-!) terms are found in the range parameter, the exclusive terms are interpreted as exceptions to the inclusive terms. That is, a page will be included in the generated archive if and only if it appears in at least one inclusive term and it does not appear in any exclusive term. For example, the range value odd,!3 indicates that pages 1, 5, 7 and 9 should be included.

Note that page numbering starts at 1.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the “Split a PDF into pages” demo for a live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/-/rendition/pages.zip

Produces

application/zip
application/json

Parameters

document

required, file, formData

Document to be split into individual pages.

  Choose a File...  

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the rendition is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the rendition has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/documents/{doc_ids}/rendition/combined.pdf
Join a series of previously-stored documents into a single PDF.
 

Description

Generates and returns (or stores) a PDF document that concatenates the given documents in order.

Currently this method accepts input documents in Microsoft Office (.doc/.docx, .ppt/.pptx, .xls/.xlsx, etc.), PDF, image (.png, .jpg, etc.), HTML and plain-text formats. This method only returns documents in the PDF format.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the “Combine PDF documents” and “Combine arbitrary documents” demos for live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/documents/{doc_ids}/rendition/combined.pdf

Produces

application/json
application/pdf

Parameters

doc_ids

required, string, path

Comma-delimited list of document identifiers for documents to be combined.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the rendition is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the rendition has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/documents/-/rendition/combined.pdf
Join a series of uploaded documents into a single PDF.
 

Description

Generates and returns (or stores) a PDF document that concatenates the given documents in order.

Currently this method accepts input documents in Microsoft Office (.doc/.docx, .ppt/.pptx, .xls/.xlsx, etc.), PDF, image (.png, .jpg, etc.), HTML and plain-text formats. This method only returns documents in the PDF format.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

NOTE: In order to work around a limitation of Swagger UI (the nifty open source framework that is used to generate this API documentation), the form below supports at most 5 source documents. The actual API method supports an array of files under document key.

See the “Combine PDF documents” and “Combine arbitrary documents” demos for live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/documents/-/rendition/combined.pdf

Produces

application/json
application/zip

Parameters

document

required, file, formData

Document to be combined

  Choose a File...  

document

optional, file, formData

Document to be combined

  Choose a File...  

document

optional, file, formData

Document to be combined

  Choose a File...  

document

optional, file, formData

Document to be combined

  Choose a File...  

document

optional, file, formData

Document to be combined

  Choose a File...  

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the rendition is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the rendition has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/document/{doc_id}/watermark/{watermark_id}/rendition/pdf
Add a previously-stored “watermark” image to a previously-stored document.
 

Description

Stamps the given image on each page of the given PDF document.

Currently document must be a PDF document and watermark must be a PNG image (with or without transparency).

The query string parameters determine the placement and size of the watermark image, as described below.

  • The width and height parameters determine the size of the final watermark image, but their precise meaning depends on the value of the unit parameter.
    • When unit is px, the watermark will be placed within a width-by-height pixel area on each page — scaling the source image down (while preserving the original aspect ratio) if necessary.
    • When unit is pct, width and height represent the fraction of the overall page size that the watermark should occupy. If necessary, the source image will be scaled down (while preserving the original aspect ratio) to fit within this area.
    • When unit is in, the watermark will be placed within a width-by-height inch area on each page — scaling the source image down (while preserving the original aspect ratio) if necessary.
    • When unit is cm, the watermark will be placed within a width-by-height centimeter area on each page — scaling the source image down (while preserving the original aspect ratio) if necessary.
  • When unit is cm or in, one may provide a ppu parameter specifying the number of pixels-per-unit-size to assume for the output document if such a value cannot be determined from the PDF document itself. When ppu is not specified and no PPI/PPC/DPI/DPC value can be determined from the PDF document, a default of value of 72 pixels-per-inch (28 pixels-per-centimeter) will be assumed.
  • The gravity parameter specifies the placement of the watermark on each page of the document. When gravity is nw the watermark will be placed in the upper-left corner of the page. When n, the watermark will centered along the top edge of the page. When ne, the watermark will be placed in the top-right corner of the page. When e, the watermark will be centered along the right edge of the page. And so on. When gravity is c, the watermark will be centered on the page.
  • The opacity parameter specifies the degree to which the watermark obscures the content below it. A value of 1 is fully opaque — (any non-transparent areas of) the watermark will completely cover the background content. A value of 0 is fully transparent — the background content will be 100% visible and the watermark will not appear. At values between 0 and 1 the background content will be partially visible beneath the watermark.
    • Note that the opacity parameter does not interfere with any transparent areas in the original watermark image. Transparent portions of the source image will still be transparent, even when the watermark is set to 100% opacity.
  • When the marginwidth or marginheight parameters are specified, the watermark will be placed the specified distance from the edge of the document, but the precise meaning depends on the value of the marginunit parameter.
    • When marginunit is px (the default), the marginwidth and marginheight values are interpreted as pixels.
    • When marginunit is pct, the marginwidth and marginheight values are interpreted as a percentage of the overall size of the document.
    • When marginunit is in, the marginwidth and marginheight values are interpreted as a decimal number of inches, based on the PPU value or the document default.
    • When marginunit is cm, the marginwidth and marginheight values are interpreted as a decimal number of centimeters, based on the PPU value or the document default.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the “Watermark PDF” demo for a live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/watermark/{watermark_id}/rendition/pdf

Produces

application/pdf
application/json

Parameters

doc_id

required, string, path

Identifier for the PDF document to be watermarked

watermark_id

required, string, path

Identifier for the PNG image containing the watermark

width

optional, integer, query

Width of the watermark when stamped on to the PDF document. (See description for details.)
(value >= 0)

height

optional, integer, query

Height of the watermark when stamped on to the PDF document. (See description for details.)
(value >= 0)

unit

optional, string, query

Unit in which width and height are specified. (See description for details.)
Accepts: px, pct, in, cm

ppu

optional, integer, query

The number of pixels (dots) per unit size to assume when applying inch or centimeter watermark sizes. Only relevant when unit is in or cm. (See description for details.)
(value > 0)

marginwidth

optional, integer, query

Margin or padding at the right or left of the watermark image when stamped on to the PDF document. (See description for details.)
(value >= 0)

marginheight

optional, integer, query

Margin or padding at the top or bottom of the watermark image when stamped on to the PDF document. (See description for details.)
(value >= 0)

marginunit

optional, string, query

Unit in which marginwidth and marginheight values are specified. Defaults to px.(See description for details.)
Accepts: px, pct, in, cm

gravity

optional, string, query

Placement of the watermark on each PDF page. Defaults to sw (bottom-left)
Accepts: n, ne, e, se, s, sw, w, nw, c

opacity

optional, number, query

Opacity of the watermark image when stamped on the PDF. Defaults to 1.
(0 <= value <= 1)

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the watermarked document image is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the watermarked document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/-/watermark/-/rendition/pdf
Add an uploaded “watermark” image to an uploaded document.
 

Description

Stamps the given image on each page of the given PDF document.

Currently document must be a PDF document and watermark must be a PNG image (with or without transparency).

The query string parameters determine the placement and size of the watermark image, as described below.

  • The width and height parameters determine the size of the final watermark image, but their precise meaning depends on the value of the unit parameter.
    • When unit is px, the watermark will be placed within a width-by-height pixel area on each page — scaling the source image down (while preserving the original aspect ratio) if necessary.
    • When unit is pct, width and height represent the fraction of the overall page size that the watermark should occupy. If necessary, the source image will be scaled down (while preserving the original aspect ratio) to fit within this area.
    • When unit is in, the watermark will be placed within a width-by-height inch area on each page — scaling the source image down (while preserving the original aspect ratio) if necessary.
    • When unit is cm, the watermark will be placed within a width-by-height centimeter area on each page — scaling the source image down (while preserving the original aspect ratio) if necessary.
  • When unit is cm or in, one may provide a ppu parameter specifying the number of pixels-per-unit-size to assume for the output document if such a value cannot be determined from the PDF document itself. When ppu is not specified and no PPI/PPC/DPI/DPC value can be determined from the PDF document, a default of value of 72 pixels-per-inch (28 pixels-per-centimeter) will be assumed.
  • The gravity parameter specifies the placement of the watermark on each page of the document. When gravity is nw the watermark will be placed in the upper-left corner of the page. When n, the watermark will centered along the top edge of the page. When ne, the watermark will be placed in the top-right corner of the page. When e, the watermark will be centered along the right edge of the page. And so on. When gravity is c, the watermark will be centered on the page.
  • The opacity parameter specifies the degree to which the watermark obscures the content below it. A value of 1 is fully opaque — (any non-transparent areas of) the watermark will completely cover the background content. A value of 0 is fully transparent — the background content will be 100% visible and the watermark will not appear. At values between 0 and 1 the background content will be partially visible beneath the watermark.
    • Note that the opacity parameter does not interfere with any transparent areas in the original watermark image. Transparent portions of the source image will still be transparent, even when the watermark is set to 100% opacity.
  • When the marginwidth or marginheight parameters are specified, the watermark will be placed the specified distance from the edge of the document, but the precise meaning depends on the value of the marginunit parameter.
    • When marginunit is px (the default), the marginwidth and marginheight values are interpreted as pixels.
    • When marginunit is pct, the marginwidth and marginheight values are interpreted as a percentage of the overall size of the document.
    • When marginunit is in, the marginwidth and marginheight values are interpreted as a decimal number of inches, based on the PPU value or the document default.
    • When marginunit is cm, the marginwidth and marginheight values are interpreted as a decimal number of centimeters, based on the PPU value or the document default.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the “Watermark PDF” demo for a live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/-/watermark/-/rendition/pdf

Produces

application/pdf
application/json

Parameters

document

required, file, formData

PDF document to be watermarked

  Choose a File...  

watermark

required, file, formData

PNG image containing the watermark

  Choose a File...  

width

optional, integer, query

Width of the watermark when stamped on to the PDF document. (See description for details.)
(value >= 0)

height

optional, integer, query

Height of the watermark when stamped on to the PDF document. (See description for details.)
(value >= 0)

unit

optional, string, query

Unit in which width and height are specified. (See description for details.)
Accepts: px, pct, in, cm

ppu

optional, integer, query

The number of pixels (dots) per unit size to assume when applying inch or centimeter watermark sizes. Only relevant when unit is in or cm. (See description for details.)
(value > 0)

marginwidth

optional, integer, query

Margin or padding at the right or left of the watermark image when stamped on to the PDF document. (See description for details.)
(value >= 0)

marginheight

optional, integer, query

Margin or padding at the top or bottom of the watermark image when stamped on to the PDF document. (See description for details.)
(value >= 0)

marginunit

optional, string, query

Unit in which marginwidth and marginheight values are specified. Defaults to px.(See description for details.)
Accepts: px, pct, in, cm

gravity

optional, string, query

Placement of the watermark on each PDF page. Defaults to sw (bottom-left)
Accepts: n, ne, e, se, s, sw, w, nw, c

opacity

optional, number, query

Opacity of the watermark image when stamped on the PDF. Defaults to 1.
(0 <= value <= 1)

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the watermarked document image is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the watermarked document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/{doc_id}/watermark/-/rendition/pdf
Add an uploaded “watermark” image to a previously-stored document.
 

Description

Stamps the given image on each page of the given PDF document.

Currently document must be a PDF document and watermark must be a PNG image (with or without transparency).

The query string parameters determine the placement and size of the watermark image, as described below.

  • The width and height parameters determine the size of the final watermark image, but their precise meaning depends on the value of the unit parameter.
    • When unit is px, the watermark will be placed within a width-by-height pixel area on each page — scaling the source image down (while preserving the original aspect ratio) if necessary.
    • When unit is pct, width and height represent the fraction of the overall page size that the watermark should occupy. If necessary, the source image will be scaled down (while preserving the original aspect ratio) to fit within this area.
    • When unit is in, the watermark will be placed within a width-by-height inch area on each page — scaling the source image down (while preserving the original aspect ratio) if necessary.
    • When unit is cm, the watermark will be placed within a width-by-height centimeter area on each page — scaling the source image down (while preserving the original aspect ratio) if necessary.
  • When unit is cm or in, one may provide a ppu parameter specifying the number of pixels-per-unit-size to assume for the output document if such a value cannot be determined from the PDF document itself. When ppu is not specified and no PPI/PPC/DPI/DPC value can be determined from the PDF document, a default of value of 72 pixels-per-inch (28 pixels-per-centimeter) will be assumed.
  • The gravity parameter specifies the placement of the watermark on each page of the document. When gravity is nw the watermark will be placed in the upper-left corner of the page. When n, the watermark will centered along the top edge of the page. When ne, the watermark will be placed in the top-right corner of the page. When e, the watermark will be centered along the right edge of the page. And so on. When gravity is c, the watermark will be centered on the page.
  • The opacity parameter specifies the degree to which the watermark obscures the content below it. A value of 1 is fully opaque — (any non-transparent areas of) the watermark will completely cover the background content. A value of 0 is fully transparent — the background content will be 100% visible and the watermark will not appear. At values between 0 and 1 the background content will be partially visible beneath the watermark.
    • Note that the opacity parameter does not interfere with any transparent areas in the original watermark image. Transparent portions of the source image will still be transparent, even when the watermark is set to 100% opacity.
  • When the marginwidth or marginheight parameters are specified, the watermark will be placed the specified distance from the edge of the document, but the precise meaning depends on the value of the marginunit parameter.
    • When marginunit is px (the default), the marginwidth and marginheight values are interpreted as pixels.
    • When marginunit is pct, the marginwidth and marginheight values are interpreted as a percentage of the overall size of the document.
    • When marginunit is in, the marginwidth and marginheight values are interpreted as a decimal number of inches, based on the PPU value or the document default.
    • When marginunit is cm, the marginwidth and marginheight values are interpreted as a decimal number of centimeters, based on the PPU value or the document default.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the “Watermark PDF” demo for a live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/watermark/-/rendition/pdf

Produces

application/pdf
application/json

Parameters

doc_id

required, string, path

Identifier for the PDF document to be watermarked

watermark

required, file, formData

PNG image containing the watermark

  Choose a File...  

width

optional, integer, query

Width of the watermark when stamped on to the PDF document. (See description for details.)
(value >= 0)

height

optional, integer, query

Height of the watermark when stamped on to the PDF document. (See description for details.)
(value >= 0)

unit

optional, string, query

Unit in which width and height are specified. (See description for details.)
Accepts: px, pct, in, cm

ppu

optional, integer, query

The number of pixels (dots) per unit size to assume when applying inch or centimeter watermark sizes. Only relevant when unit is in or cm. (See description for details.)
(value > 0)

marginwidth

optional, integer, query

Margin or padding at the right or left of the watermark image when stamped on to the PDF document. (See description for details.)
(value >= 0)

marginheight

optional, integer, query

Margin or padding at the top or bottom of the watermark image when stamped on to the PDF document. (See description for details.)
(value >= 0)

marginunit

optional, string, query

Unit in which marginwidth and marginheight values are specified. Defaults to px.(See description for details.)
Accepts: px, pct, in, cm

gravity

optional, string, query

Placement of the watermark on each PDF page. Defaults to sw (bottom-left)
Accepts: n, ne, e, se, s, sw, w, nw, c

opacity

optional, number, query

Opacity of the watermark image when stamped on the PDF. Defaults to 1.
(0 <= value <= 1)

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the watermarked document image is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the watermarked document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/-/watermark/{watermark_id}/rendition/pdf
Add a previously-stored “watermark” image to an uploaded document.
 

Description

Stamps the given image on each page of the given PDF document.

Currently document must be a PDF document and watermark must be a PNG image (with or without transparency).

The query string parameters determine the placement and size of the watermark image, as described below.

  • The width and height parameters determine the size of the final watermark image, but their precise meaning depends on the value of the unit parameter.
    • When unit is px, the watermark will be placed within a width-by-height pixel area on each page — scaling the source image down (while preserving the original aspect ratio) if necessary.
    • When unit is pct, width and height represent the fraction of the overall page size that the watermark should occupy. If necessary, the source image will be scaled down (while preserving the original aspect ratio) to fit within this area.
    • When unit is in, the watermark will be placed within a width-by-height inch area on each page — scaling the source image down (while preserving the original aspect ratio) if necessary.
    • When unit is cm, the watermark will be placed within a width-by-height centimeter area on each page — scaling the source image down (while preserving the original aspect ratio) if necessary.
  • When unit is cm or in, one may provide a ppu parameter specifying the number of pixels-per-unit-size to assume for the output document if such a value cannot be determined from the PDF document itself. When ppu is not specified and no PPI/PPC/DPI/DPC value can be determined from the PDF document, a default of value of 72 pixels-per-inch (28 pixels-per-centimeter) will be assumed.
  • The gravity parameter specifies the placement of the watermark on each page of the document. When gravity is nw the watermark will be placed in the upper-left corner of the page. When n, the watermark will centered along the top edge of the page. When ne, the watermark will be placed in the top-right corner of the page. When e, the watermark will be centered along the right edge of the page. And so on. When gravity is c, the watermark will be centered on the page.
  • The opacity parameter specifies the degree to which the watermark obscures the content below it. A value of 1 is fully opaque — (any non-transparent areas of) the watermark will completely cover the background content. A value of 0 is fully transparent — the background content will be 100% visible and the watermark will not appear. At values between 0 and 1 the background content will be partially visible beneath the watermark.
    • Note that the opacity parameter does not interfere with any transparent areas in the original watermark image. Transparent portions of the source image will still be transparent, even when the watermark is set to 100% opacity.
  • When the marginwidth or marginheight parameters are specified, the watermark will be placed the specified distance from the edge of the document, but the precise meaning depends on the value of the marginunit parameter.
    • When marginunit is px (the default), the marginwidth and marginheight values are interpreted as pixels.
    • When marginunit is pct, the marginwidth and marginheight values are interpreted as a percentage of the overall size of the document.
    • When marginunit is in, the marginwidth and marginheight values are interpreted as a decimal number of inches, based on the PPU value or the document default.
    • When marginunit is cm, the marginwidth and marginheight values are interpreted as a decimal number of centimeters, based on the PPU value or the document default.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the “Watermark PDF” demo for a live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/-/watermark/{watermark_id}/rendition/pdf

Produces

application/pdf
application/json

Parameters

document

required, file, formData

PDF document to be watermarked

  Choose a File...  

watermark_id

required, string, path

Identifier for the PNG image containing the watermark

width

optional, integer, query

Width of the watermark when stamped on to the PDF document. (See description for details.)
(value >= 0)

height

optional, integer, query

Height of the watermark when stamped on to the PDF document. (See description for details.)
(value >= 0)

unit

optional, string, query

Unit in which width and height are specified. (See description for details.)
Accepts: px, pct, in, cm

ppu

optional, integer, query

The number of pixels (dots) per unit size to assume when applying inch or centimeter watermark sizes. Only relevant when unit is in or cm. (See description for details.)
(value > 0)

marginwidth

optional, integer, query

Margin or padding at the right or left of the watermark image when stamped on to the PDF document. (See description for details.)
(value >= 0)

marginheight

optional, integer, query

Margin or padding at the top or bottom of the watermark image when stamped on to the PDF document. (See description for details.)
(value >= 0)

marginunit

optional, string, query

Unit in which marginwidth and marginheight values are specified. Defaults to px.(See description for details.)
Accepts: px, pct, in, cm

gravity

optional, string, query

Placement of the watermark on each PDF page. Defaults to sw (bottom-left)
Accepts: n, ne, e, se, s, sw, w, nw, c

opacity

optional, number, query

Opacity of the watermark image when stamped on the PDF. Defaults to 1.
(0 <= value <= 1)

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the watermarked document image is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the watermarked document has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

GET/document/{doc_id}/rendition/{format}/transform/{actions}
Transform a previously stored image by applying the specified action(s).
 

Description

Generates and returns (or stores) an image by applying the specified transformations to the specified document.

Currently this method accepts input images in most common formats (including PNG, JPG, GIF, BMP, WEBP and TIFF) and generates PNG, JPG or WEBP documents (with varying levels of compression).

The actions path segment(s) define a series of (slash-delimited) transformations to apply to the image.

  • S<width>,<height> - preserving the original aspect-ratio, resize the image such the image's width or height matches at least one of the specified values

  • s<width>,<height> - exactly like the S<width>,<height> case, save that the image will NOT be enlarged if it already fits within the specified bounds.

  • S<width>,<height>,<gravity> - preserving the original aspect-ratio, resize the image such that the image's height and width are at least as large as the specified values THEN crop the image to the exact dimensions specified.

    The <gravity> parameter specifies which part of the image to crop to:

    • c (center) - the "detail" will be taken from the center of the given image.
    • n (north) - the "detail" will be taken from the top edge of the given image (centered horizontally).
    • s (south) - the "detail" will be taken from the bottom edge of the given image (centered horizontally).
    • e (east) - the "detail" will be taken from the right edge of the given image (centered vertically).
    • w (west) - the "detail" will be taken from the left edge of the given image (centered vertically).
  • S<width>,<height>,<red>,<green>,<blue>[.<alpha>] - embed the original image in the center of a <width>-by-<height> image with the specified RGB or RGBA value as the background color.

    <red>, <green> and <blue> should be integers between 0 and 255 (inclusive).

    <alpha>, when present, should be a decimal value between 0 and 1. (When missing, <alpha> defaults to 1 — fully opaque.)

  • X<top>,<left>,<width>,<height> - extract the specified section of the image.

  • R90, R180, R270 - rotate the image by 90, 180 or 270 degrees, clockwise.

  • RA - use the source image's EXIF data (if any) to automatically orient the image.

  • Fx, Fy - flip the image over the X or Y axis, respectively.

  • B[<radius>] - blur the image, using the optional <radius> when provided.

  • P[<radius>[,<flat>[,<jagged>]]] - sharpen the image, using the optional <radius> when provided.

  • GS - convert the image to gray-scale. (Note that this does not apply to the background color used with S<width>,<height>,<red>,<green>,<blue>[.<alpha>].)

The format parameter determines the file format of the generated document. The basic formats are png, jpg and webp. However, each accepts an optional numeric suffix that identifies the level of compression or quality to apply:

  • png[<compression>] - converts the image to the PNG format, using the optional <compression> factor (1-9) if specified.

  • jpeg[<quality>] - converts the image to the JPEG format, using the optional <quality> factor (0-100) if specified.

  • webp[<quality>] - converts the image to the WEBP format, using the optional <quality> factor (0-100) if specified.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the “Transform Image” demo for a live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/{doc_id}/rendition/{format}/transform/{actions}

Produces

application/json
image/png
image/jpeg
image/webp

Parameters

doc_id

required, string, path

Identifier for the image to be transformed

format

required, string, path

Format for the generated document. See the implementation notes above for details.
Accepts: png, jpg, png1, png2, png3, png4, png6, png7, png8, png9, jpg10, jpg20, jpg30, jpg40, jpg50, jpg60, jpg70, jpg80, jpg90, jpg100

actions

required, string, path

Slash-delimited series of transformations to apply. See the implementation notes above for details.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the rendition is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the rendition has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...

POST/document/-/rendition/{format}/transform/{actions}
Transform an uploaded image by applying the specified action(s).
 

Description

Generates and returns (or stores) an image by applying the specified transformations to the specified document.

Currently this method accepts input images in most common formats (including PNG, JPG, GIF, BMP, WEBP and TIFF) and generates PNG, JPG or WEBP documents (with varying levels of compression).

The actions path segment(s) define a series of (slash-delimited) transformations to apply to the image.

  • S<width>,<height> - preserving the original aspect-ratio, resize the image such the image's width or height matches at least one of the specified values

  • s<width>,<height> - exactly like the S<width>,<height> case, save that the image will NOT be enlarged if it already fits within the specified bounds.

  • S<width>,<height>,<gravity> - preserving the original aspect-ratio, resize the image such that the image's height and width are at least as large as the specified values THEN crop the image to the exact dimensions specified.

    The <gravity> parameter specifies which part of the image to crop to:

    • c (center) - the "detail" will be taken from the center of the given image.
    • n (north) - the "detail" will be taken from the top edge of the given image (centered horizontally).
    • s (south) - the "detail" will be taken from the bottom edge of the given image (centered horizontally).
    • e (east) - the "detail" will be taken from the right edge of the given image (centered vertically).
    • w (west) - the "detail" will be taken from the left edge of the given image (centered vertically).
  • S<width>,<height>,<red>,<green>,<blue>[.<alpha>] - embed the original image in the center of a <width>-by-<height> image with the specified RGB or RGBA value as the background color.

    <red>, <green> and <blue> should be integers between 0 and 255 (inclusive).

    <alpha>, when present, should be a decimal value between 0 and 1. (When missing, <alpha> defaults to 1 — fully opaque.)

  • X<top>,<left>,<width>,<height> - extract the specified section of the image.

  • R90, R180, R270 - rotate the image by 90, 180 or 270 degrees, clockwise.

  • RA - use the source image's EXIF data (if any) to automatically orient the image.

  • Fx, Fy - flip the image over the X or Y axis, respectively.

  • B[<radius>] - blur the image, using the optional <radius> when provided.

  • P[<radius>[,<flat>[,<jagged>]]] - sharpen the image, using the optional <radius> when provided.

  • GS - convert the image to gray-scale. (Note that this does not apply to the background color used with S<width>,<height>,<red>,<green>,<blue>[.<alpha>].)

The format parameter determines the file format of the generated document. The basic formats are png, jpg and webp. However, each accepts an optional numeric suffix that identifies the level of compression or quality to apply:

  • png[<compression>] - converts the image to the PNG format, using the optional <compression> factor (1-9) if specified.

  • jpeg[<quality>] - converts the image to the JPEG format, using the optional <quality> factor (0-100) if specified.

  • webp[<quality>] - converts the image to the WEBP format, using the optional <quality> factor (0-100) if specified.

By default, this method will return the generated rendition in the body of the HTTP response (with an appropriate Content-Type header).

When the store parameter is set to true, the generated document will be placed in the document store and a JSON document containing a document identifier will be returned instead (as if the generated document was uploaded via the POST /document API method).

An optional ttl ("Time-To-Live") parameter specifies (in seconds) how long the document should be stored. When omitted, a duration of 3600 seconds (one hour) is used by default. The maximum TTL value is currently 86400 seconds (one day). ttl values greater than 86400 seconds will be capped to 86400.

See the “Transform Image” demo for a live example of this functionality.

Full Resource URL

https://documentalchemy.com/api/v1/document/-/rendition/{format}/transform/{actions}

Produces

application/json
image/png
image/jpeg
image/webp

Parameters

document

required, file, formData

Document to be transformed

  Choose a File...  

format

required, string, path

Format for the generated document. See the implementation notes above for details.
Accepts: png, jpg, png1, png2, png3, png4, png6, png7, png8, png9, jpg10, jpg20, jpg30, jpg40, jpg50, jpg60, jpg70, jpg80, jpg90, jpg100

actions

required, string, path

Slash-delimited series of transformations to apply. See the implementation notes above for details.

store

optional, boolean, query

When true, add the resulting file to the document store rather than returning it directly. Defaults to false.

ttl

optional, integer, query

Duration for which to keep the document in storage, expressed in seconds. Defaults to 3600 (one hour). Maximum allowed value is 86400 (one day).
(1 <= value <= 86400)

 
 

Standard Responses

200

An HTTP 200 response is returned when store is not true. It indicates that the rendition is available in the response body.

201

An HTTP 201 response is returned when store is true. It indicates that the rendition has been stored and can be accessed using the document identifier specified in the response body.

Error Responses...


Copyright © 2017 DocumentAlchemy.