Basic Usage

To create a new document from a file, POST its contents to /api/documents, specifying the correct content type.

You can create a document in any of the supported file formats and then use the functionality of both the Web API and Document Engine-Server API.

Document Engine will extract the title of the document from the file metadata if it is present.

Advanced Usage

Document Engine also supports uploading files as multipart/form-data. When using this method, Document Engine will try reading the title from the file metadata and fall back to the filename if the metadata is not available.

When using multipart/form-data you can also attach an XFDF or Instant JSON file to be applied to the imported document. This feature is available both for direct file upload and importing from remote URL, however, note that you should specify either url (and optionally sha256) or file, not both at the same time.

While using this request format you can also specify a custom title or document_id.

Adding a Document from a URL

You can also add a document to Document Engine by specifying the URL the document can be fetched from. By default, a document added by a URL is not persistently stored in Document Engine and will be fetched from the URL when necessary. This is useful when you already have a document storage solution and you want Document Engine to fetch the documents from your document storage. You can override this default storage behavior to store the document persistently by setting a copy_asset_to_storage_backend option to true.

To add a document from a URL, POST its URL — and optionally, its SHA256 hash, your document_id, and your title — using the application/json content type.

Processing Document on Upload

Document Engine supports processing documents via Build API. This allows you to assemble a PDF from multiple parts, such as an existing document in supported content type, a blank page, or an HTML page. You can apply one or more actions, such as watermarking, rotating pages, or importing annotations. Once the entire PDF is generated from its parts, you can also apply additional actions, such as optical character recognition (OCR), to the assembled PDF itself.

To Process the document using The Build API, you'll need to provide all inputs and the Build instructions:

• Use multipart/form-data with special instructions part with the processing instructions. You can pass any options allowed by the other document creation methods - document_id, title, etc. - as parts in the multipart request.
• If all inputs are provided as remote URLs, the multipart request isn't necessary and can be simplified to a simple non-multipart request with the application/json body with the processing instructions provided as instructions key.

Null Byte Handling

Null bytes (\u0000) are handled differently depending on the field:

• document_id, url, and storage values are validated and rejected with 422 if they contain null bytes.
• Document property strings (for example title and extracted PDF metadata) are sanitized before persistence: leading and trailing null bytes are removed, and one or more consecutive inner null bytes are replaced with a single space.

Configuring Storage

By default, Document Engine will store all assets associated with the document - images, PDF, source files that were converted, etc. in the built-in storage. If the ASSET_STORAGE_BACKEND is configured, then Document Engine will use that instead of built_in.

That said, when uploading a document you can optionally pass in some storage configuration options to control where the document's assets are stored by setting the storage field. For example, you can specify the exact s3 bucket for storage of the document's assets. You can also specify that a given document should be stored in Azure Blob Storage or with the built_in storage.

This configuration will override any default storage backends set in Document Engine's ASSET_STORAGE_BACKEND configuration. and it will be used to store all assets associated with the document - images, PDF, source files that were converted, etc.

⚠️ NOTE: The backend configured in storage must be enabled as either the main storage backend or as a fallback otherwise the upload will be done using the default enabled storage after logging a warning. Learn more about configuring Asset Storage for Document Engine here

{
  "instructions": {
    "parts": [
      {
        "file": "pdf-file-from-multipart"
      }
    ],
    "actions": [
      {
        "file": {
          "url": "https://remote-file-storage/input-file"
        }
      }
    ],
    "output": {
      "metadata": {
        "title": "Nutrient Document Engine API Specification",
        "author": "Document Author"
      },
      "labels": [
        {
          "label": "Page I-III"
        }
      ]
    }
  },
  "document_id": "7KPSE41NWKDGK5T9CFS3S53JTP"
}

{
  "data": {
    "document_id": "7KPZW8XFGM4F1C92KWBK1B748M",
    "password_protected": true,
    "sourcePdfSha256": "1defd934dbbf77587eb9b7f45d162d2a3aea16c840a9e7cfa190fb2ea1f40a76",
    "title": "Nutrient Document Engine API Specification",
    "createdAt": "2019-09-16T15:05:03.712909Z"
  }
}