This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/document-engine/annotations/import-and-export/instant-json.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Import and export JSON PDF annotation data server-side

Import and export Instant JSON PDF annotation data

Markdown version of this page, suitable for AI agents and automation

You can import and export annotations from documents you’ve uploaded to Document Engine. One of the supported formats for this is Instant JSON. This guide explains how to import and export annotations in the Instant JSON format.

Exporting Instant JSON

You can export the current annotations of a document as an Instant JSON file via a GET request to /api/documents/:document_id/document.json. To get the current annotations of a layer, send a GET request to /api/documents/:document_id/layers/:layer_name/document.json:

Request

GET /api/documents/:document_id/document.json
Authorization: Token token="<secret token>"
Terminal window
$ curl "http://localhost:5000/api/documents/abc/document.json" \
   -H "Authorization: Token token=<secret token>"

By default, Document Engine returns a full export. In Document Engine 1.17 and later, you can add type=diff to exclude unmodified form fields and widget annotations that originated from the uploaded PDF:

Terminal window
$ curl "http://localhost:5000/api/documents/abc/document.json?type=diff" \
   -H "Authorization: Token token=<secret token>"

Use type=diff when applying the export to another copy of the original PDF, where those unmodified base-PDF form fields already exist. The type parameter only affects form fields and widget annotations; other records and form field values are included in both full and diff exports.

Both full and diff exports return the same response shape: a 200 OK response with Instant JSON. The difference is in the JSON payload: type=diff omits unmodified base-PDF form fields and widget annotations.

Successful response

HTTP/1.1 200 OK
Content-Type: application/json


<JSON data>

Requests with invalid type values are rejected with a 400 response.

Importing Instant JSON

Document Engine supports importing annotations from an Instant JSON file when uploading a document via the /api/documents endpoint. Send a multipart/form-data POST request, including the PDF and the Instant JSON file, to import the annotations in the given PDF file. This will replace all existing annotations in the uploaded PDF with the annotations from the uploaded Instant JSON file. If you want to add annotations to already existing ones instead of replacing them, you can set keep_current_annotations to true:

Request

POST /api/documents
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token="<secret token>"


--customboundary
Content-Disposition: form-data; name="file"; filename="Example Document.pdf"
Content-Type: application/pdf


<PDF data>
--customboundary
Content-Disposition: form-data; name="attachment"; filename="attachment.json"
Content-Type: application/json


<annotations data>
--customboundary

Importing Instant JSON on existing documents

Document Engine supports importing annotations from an Instant JSON file on an existing document via three different endpoints:

  • POST /apply_instant_json receives an instant.json file and updates the document in place using the instant.json file.
  • POST /pdf_with_instant_json receives an instant.json file and responds with the resulting PDF of the document/layer and the imported instant.json.
  • POST /copy_with_instant_json can optionally receive an instant.json file and will persist the resulting PDF of the document/layer and the imported instant.json file as a new document. The JSON response will include the document_id of the document.