This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/dws-processor/developer-guides/choose-the-right-build-api-and-server-side-assembly-workflow.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Choose the right Build API and server-side assembly workflow

Choose the right Build API and server-side assembly workflow

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

Use a server-side assembly workflow when you need to combine files or page ranges, apply document operations, or set final output options outside the browser. Document Engine and DWS Processor API both provide Build endpoints, but they’re separate products with product-specific schemas, authentication, and persistence workflows.

The same assembly goal across products

SetupRequest and resultWhen to use it
Web SDK NutrientViewer.build()The SDK calls a configured Document Engine or DWS Processor API backend with an access token, build instructions, and any required inputs. For Document Engine, this method requires version 1.6.0 or later. It returns the processed result to the client as an ArrayBuffer; your application handles delivery or storage.Use this when a Web SDK application needs to initiate backend processing through the SDK client. Keep backend credentials out of the browser and use the backend-specific token flow.
Document Engine Build APISend inputs and the Document Engine instructions object to POST /api/build. The endpoint assembles and processes the request and returns output. A normal Build request doesn’t replace or persist an existing Document Engine document on its own. Use a separate document-update workflow, such as apply_instructions, when the result should update a managed document.Use this when you operate Document Engine, need server-side assembly or transformations, and want control over deployment and document lifecycle.
DWS Processor API Build APISend inputs and Build instructions to POST https://api.nutrient.io/build. The API returns an output file for your application to store or deliver; it doesn’t create a managed document for later retrieval. For asynchronous jobs, retrieve the result before its documented expiry; see the Build document endpoint reference. Use /analyze_build to estimate credit use without executing the request.Use this when you want managed server-side document processing without operating Document Engine infrastructure.

How a Build request is assembled

A Build request generally defines the inputs to include, how to assemble them, which supported operations to perform, and the output to produce. The exact request schema and available options depend on the backend; use that backend’s API reference and examples rather than assuming payloads are interchangeable.

  1. Provide the inputs — Upload local files or reference supported remote inputs. Confirm that the selected backend and operation accept each input type.
  2. Define the output parts and order — Parts determine which documents or page ranges appear in the result and in what order. Some workflows can also include generated HTML or blank pages.
  3. Add supported operations — Apply operations such as rotation, OCR, redaction, watermarking, or annotation import only where supported. The placement and ordering of operations can differ by API and instruction schema.
  4. Set output options — Choose the output format and any supported security, conformance, optimization, or delivery options.
  5. Handle the result — Build endpoints return a result. Decide whether the application downloads it, stores it, or passes it to a separate workflow that updates a managed document.

How to choose the right Build workflow

Use Document Engine Build API when processing should run on your self-hosted Document Engine deployment. A standard POST /api/build request returns its result. To change a stored Document Engine document, use the documented operation that applies instructions to it. A file-returning Build request doesn’t update the document.

Use DWS Processor API Build API when you need a hosted document-in/document-out processing job. Use /build to execute supported instructions and /analyze_build to estimate the cost of a request before running it. Your application remains responsible for the returned output and its storage or delivery.

Use Web SDK NutrientViewer.build() when a Web SDK client needs to invoke a supported backend Build workflow. Configure authorization for the chosen backend and provide the required input data. The SDK method is a client for backend processing, not a replacement for the backend’s API or its product-specific instructions.

Common points of confusion

  • The two Build APIs aren’t one interchangeable service — Document Engine POST /api/build and DWS Processor API POST /build use product-specific authentication, schemas, capabilities, and deployment models. Check the selected product’s reference before reusing instructions.
  • Assembly order matters — The parts array defines output order. Page selection and any follow-up operations must match the intended final document.
  • Build output isn’t automatically a managed document — Store or deliver the returned file through your application unless you call a separate document-update or persistence workflow. For DWS Processor API asynchronous jobs, results are temporary. Check the Build document endpoint reference for the expiry, and retrieve the output before then.
  • Input references have security implications — Keep credentials server-side, validate user access to each input, and accept only remote URLs that your application is permitted to process.
  • Operations and output formats are bounded by support — Build APIs support documented input formats, output types, and actions, not arbitrary combinations. Verify each operation and its ordering for the selected product.
  • Estimate versus execute — DWS Processor API /analyze_build estimates and validates a request; /build performs the processing.
  • Cryptographic signing may use a separate endpoint — Don’t assume every finalization task is a Build action. Follow the product-specific signing workflow and perform operations in the required order.

Typical decision questions

  1. Is processing self-hosted on Document Engine or managed through DWS Processor API?
  2. Should the request be initiated by a Web SDK client through NutrientViewer.build() or directly by your backend?
  3. Which files, page ranges, and generated content make up the final output, and in what order?
  4. Which actions are required, and does the chosen API support them at the needed stage?
  5. Should the output be returned to your application, or should a separate operation update a stored Document Engine document?
  6. For DWS Processor API, should you estimate the request with /analyze_build before executing it?

Guides by product