Collabora Online document conversion API guide

Collabora Online document conversion API for on-premises conversion

A platform team that needs PDFs, previews or image renders from Office files, without sending those files to an outside conversion service, can use Collabora Online itself as the conversion engine. The same coolwsd server that serves browser editing also exposes an HTTP convert-to endpoint, so no separate conversion product has to be installed in the same network zone. Requests are an HTTP POST to /cool/convert-to/<format>, where the format is the target type, such as PDF or PNG. Teams usually reach for this when documents must stay inside their own infrastructure, when a system such as Nextcloud needs previews, or when a batch job, archive or records workflow needs a rendered copy of a Word, Excel or PowerPoint file. The supported output formats depend on the document type. For text documents the endpoint can produce formats such as docx, odt, pdf and rtf. For spreadsheets it covers xlsx, ods and csv, and for presentations pptx, odp and pdf. Image renders such as PNG are also part of the use case the endpoint is built for. Confirm the exact input and output matrix for your release against Collabora's document conversion guidance before you write a conversion step into a pipeline, because fidelity differs between a rendered PDF and a round trip back to Office formats, and those differences should be tested on your own files. Use the editing path instead when a person needs to change the document, and use the conversion path when a machine needs a fixed output. Before going live, decide who may call the endpoint. Nextcloud previews require the Nextcloud host IP to be added to the net.post_allow.host allow list through coolconfig, so every other caller should be refused by default and added only with a documented owner. Plan the allow list, network policy and logging together, and test a denied caller and an allowed caller on the same build.

Configuration options and when each fits

This table compares the main ways to run Collabora Online as a conversion service, from conversion-only use to shared editing and preview, from a single server to a pool, and from internal callers to broader access. Read each row as a decision: the fit column names the situation, and the trade-off column names what you accept and what you must confirm before going live.

Option	When it fits	Trade-off to weigh	Check before choosing
Conversion only	A back-end job or service calls the convert-to endpoint and no user opens documents in the browser	Fewer moving parts, but you still need the same allow list and access controls as any WOPI host	Confirm which conversion paths your callers use and that no editing is needed
Shared editing and previews	Nextcloud users edit documents and also see previews generated by the same server	Editing sessions and conversion calls share memory and CPU, so load from one can affect the other	Confirm the Nextcloud host IP is in net.post_allow.host and size for both workloads
Single server	Low or predictable volume, a test or pilot, or a small team	Simple to run, but one failure stops both editing and conversions	Confirm expected conversion volume and whether a restart window is acceptable
Pool behind a load balancer	Higher volume or availability needs across several servers or pods	Requests for one document must reach the same server, so the balancer must route by WOPISrc	Confirm your load balancer can route by WOPISrc and that convert-to calls are handled as you expect
Internal-only callers	Conversion requests come from a fixed set of internal hosts you can list by IP	Narrow exposure and simple allow lists, but new internal services need a change to the list	Confirm the full list of caller addresses and how changes are approved
Broader callers	Several departments, partners or external platforms send conversion requests	More callers mean a larger attack surface and a harder allow list to keep accurate	Confirm authentication options at the proxy layer and the review process for new callers
Startup, convert and shut down tools	Occasional batch jobs with low volume and no need for a long-running service	Simple to start, but each run pays startup cost; compare throughput with Collabora Online before committing	Benchmark both with your own documents and formats, since published comparisons may not match your workload

Setting up the conversion service and allow list

This sequence takes a host from a clean server to a working on-premises conversion endpoint that only approved callers can reach. Each step ends with a check, so you know the service is ready before any application depends on it.

Confirm the target platform and install method
Your infrastructure team picks how Collabora Online will run: system packages, Docker or Kubernetes. The official Docker image for the free edition is collabora/code, which runs on x86-64, ppc64 and arm64. Note that CODE is suited to testing and small teams and is not recommended for production, so a production conversion service needs a supported Business or Enterprise plan, as set out on the pricing page. Confirm the choice with your Collabora contact before you install. You are done when the install method, host sizing and edition are written down and approved by the team that will operate the service.
Install Collabora Online on the chosen host
Your platform or operations engineers install Collabora Online on a host inside your network, following the package or container instructions for your chosen method. Keep the host reachable only from the network segment where your calling applications run. Use a current release branch and record the exact version installed, because the point releases carry security fixes. You are done when the service starts without errors and the process is listening on its configured port.
Confirm the convert-to endpoint responds
From a machine on the calling network, send a request to the service's convert-to path, which is /cool/convert-to/ followed by the target format. A request to a format such as pdf should return a response from the service rather than a connection error. This check confirms routing and TLS, not conversion quality. You are done when the endpoint answers over the protocol and hostname you plan to use in production.
Identify the calling host addresses
Your application or platform team lists every host IP address that will call the conversion API. For Nextcloud previews, this is the Nextcloud host IP. Record the addresses in a change ticket and confirm them with the network team, including any NAT or load balancer address that the service will see as the source. You are done when the list is complete and each address has an owner.
Add the caller to the net.post_allow.host allow list
Your operations engineer uses coolconfig to add each approved caller address to the net.post_allow.host setting, then restarts the service so the change takes effect. Keep the list as narrow as the callers allow, and avoid broad ranges unless you have confirmed they are needed. Store the configuration change in your configuration management system. You are done when coolconfig shows the approved addresses under that key and the service has restarted cleanly.
Test an allowed conversion to PDF or PNG
From an approved caller, submit a test document with an HTTP POST to the convert-to endpoint for PDF or PNG and save the response file. Open the output and check that the page content matches the input. Then repeat the request from a host that is not on the list and confirm it is refused. You are done when the allowed request returns a valid converted file and the unlisted request is rejected.
Record the verified configuration
Your operations team documents the installed version, the allow list entries, the test cases and their results, and the owner of each caller. Store this record alongside the runbook for upgrades and incident response. Ask your Collabora contact or the vendor documentation to confirm any allow list behavior that differs in your deployment model before go-live. You are done when the record is filed and the team that will operate the service has signed it off.

Securing who can call the conversion endpoint

A conversion endpoint accepts documents from other systems, so the controls sit in three places: which callers can reach it, how traffic and files move, and how the software stays patched. Each card below covers one of these decisions and the check to run before the service takes production traffic.

Allow-list known caller addresses

Only the IP addresses of systems that should convert documents may reach the coolwsd conversion API. For Nextcloud previews, the Nextcloud host IP must be added to the net.post_allow.host allow list using coolconfig, and Nextcloud's own guidance recommends restricting WOPI requests to known Collabora server addresses. Ask who owns each caller address, and review the list when servers are added, moved or retired, since stale entries quietly widen access.

Keep the service off public networks

Place the conversion server on an internal network segment that only approved callers can route to, behind your firewall or load balancer. A conversion endpoint has no reason to be reachable from the internet, and a document that reaches a public address cannot be recalled. Confirm the network policy with your security team and test it from an address outside the allow list to confirm the request is refused.

Encrypt traffic between caller and server

Use HTTPS between the calling platform and Collabora Online, and use the same protocol for the server URL as for the calling platform, as Nextcloud's administration guidance recommends. Unencrypted uploads expose document contents to anyone on the path. Confirm certificate issuance, renewal and trust store handling for each caller, including any internal certificate authority the callers must trust.

Set retention for uploaded documents

Conversion requests carry the full document content, so temporary copies on disk, in logs or in caller caches become part of your data handling scope. Ask the vendor and your own testing how conversion inputs and outputs are stored and cleared, then set a deletion routine for the caller side and check that logs record request metadata rather than document bodies. Document the answer for your data protection assessment.

Patch from Collabora's advisories

Collabora publishes security advisories for Collabora Online. The 25.04 release notes, for example, record that 25.04.7.5, released January 29, 2026, fixed CVE-2026-23623 and that RPM and DEB package signing keys were updated. Subscribe to release notes for your branch, test point releases in a staging conversion service, and record the version running in each environment so you can show when a fix was applied.

Throughput compared with startup-convert-shutdown tools

The key difference is that Collabora Online is a long-running service. The coolwsd process keeps the LibreOffice-based conversion engine loaded between requests, so each call to /cool/convert-to/<format> pays for the document load and export but not for starting an office process. Tools in the startup-convert-shutdown pattern, such as command-line wrappers that launch an office instance for each job and tear it down afterward, pay that startup cost every time. Whether that difference matters to you depends on how many conversions you run and how often. A low-volume workflow may not notice it. A high-volume preview or archiving pipeline may.

Throughput in either model is driven by a few factors you control. Concurrency is the main one: how many conversions the server processes at once, and how many queued requests it can hold before callers see delays or failures. Document size and complexity matter next, since a 300-page report with embedded images or a large spreadsheet with many formulas takes far longer than a one-page letter. The output format also changes the cost, because a PDF export of a presentation with rich graphics is heavier than a CSV export of a sheet. Hardware sets the ceiling, including CPU cores, memory and disk speed. The Helm chart README's production figures for a single pod are a useful starting point for sizing, but they are not a benchmark of your workload.

No supplied figures compare Collabora Online with JODConverter, unoconv or other startup-convert-shutdown tools, so do not accept a vendor or colleague's speed claim as a basis for design. Build a benchmark from your own document mix. Collect a representative sample of files by type, size and page count, then run conversions at the concurrency levels you expect at peak, recording latency, failures and memory use per pod. Repeat the test against the alternative tool on the same hardware. Ask any implementation partner to show the method and raw results in a written scope, so the comparison can be repeated after upgrades. Confirm the current capacity guidance for your version with the Collabora document conversion page before you finalize hardware.

Limits to confirm in your environment

The conversion endpoint is only as predictable as the limits behind it. The cards below list what to confirm with Collabora or in a test environment before any caller depends on the service, from format coverage to support terms.

Exact format matrix for your files

The supplied documentation lists output formats for text, spreadsheet and presentation documents, including PDF and PNG as conversion targets. Build a matrix from your own file types, such as legacy Word, macro-enabled workbooks and Visio drawings, and run each input and output pair through the endpoint. Record which pairs succeed, which degrade and which fail, and keep the matrix with the service owner's documentation.

Macros and embedded content

Confirm how the endpoint treats documents that contain macros, embedded objects or external links. Your security team should decide whether such files are accepted, stripped or rejected at the edge, and test that decision with sample files rather than assuming the converter behaves the way the desktop application does.

Fonts and complex layouts

Rendered PDF and image output depends on the fonts installed on the server. Compare output for documents with custom fonts, right-to-left text, tables that span pages and heavy graphics against the originals. Decide which fonts must be installed in the container image and who approves a change to that font set.

Maximum file sizes and page counts

Ask Collabora for the upper bounds that apply to conversion requests, and test your largest real documents at the limits you expect. Check the reverse proxy body size and request timeouts in front of the service as well, because a request that the converter accepts can still fail at the ingress before it reaches the server.

Concurrency and throughput under load

Measure how many conversions run in parallel per server before queuing or errors appear, and compare the result with your expected batch sizes. Use the sizing guidance for the Collabora Online server rather than assuming a number, and test with the resource limits your platform team will actually set.

Support coverage for the endpoint

Ask in writing whether the conversion endpoint, as opposed to the editing interface, falls under the support plan you choose. Confirm the response expectations, the patch channel for security fixes and whether the Business or Enterprise plan terms apply to a server used only for conversion.

Questions teams ask before running conversion on Collabora Online

Can our own team build a conversion service on Collabora Online?

Yes, if you have engineers comfortable with Linux, containers and HTTP services. Collabora Online exposes an HTTP POST to /cool/convert-to/<format>, so the core call is simple. The harder work is everything around it: deciding who may call the service, sizing the server for your peak batch load, testing that output matches your source files, and keeping the server patched. Many teams build the first version in-house and bring in a partner for the fidelity testing and hardening. DeployOpen plans, implements and documents this work inside your infrastructure under a written scope.

What drives the effort and cost of a conversion service?

Effort follows four drivers:

Sizing: peak concurrent conversions, document size and page counts, and how many servers you need for headroom.
Allow list design: which hosts may call the API, how they are identified, and how changes are approved.
Fidelity testing: how many file types you convert, and how closely the output must match the original.
Integration: how your applications, queues and storage call the service and handle failures.

For cost, the Collabora Online pricing page lists the Business plan at 3 euros per user per month for up to 99 users, with long term support, an SLA, signed security updates and customer portal access. Pricing is per user, so confirm with Collabora whether and how a server-to-server conversion workload is licensed.

How long does a conversion pilot take?

A pilot usually covers one environment, a defined set of formats and a small number of calling applications. Its length depends on how many document types you test, how many integrations you connect, and how quickly your security team approves network rules and the allow list. Ask for a timeline in the written scope, with milestones for sizing, fidelity sign-off and production cutover. Timelines are set in the statement of work, not estimated here.

What do we need to provide before the work starts?

Prepare these items so the scope can be fixed in writing:

A representative set of test documents in the formats you convert, including the difficult ones such as complex spreadsheets and templates with embedded fonts.
Network details: the hosts that will call the API, the IP addresses or ranges you can allow, and any proxy or firewall rules between them.
Hosting: the cloud account, data center or air-gapped network where the server will run, and the container or package platform you use.
Named contacts for security approval and for the application team that consumes the output.

Which costs are one-time and which recur?

One-time costs include scoping, sizing, building the calling integration, allow list design, fidelity testing and the initial hardening. Recurring costs include the server infrastructure, licensing if you choose a subscription, patching and point releases, monitoring, and periodic fidelity checks after upgrades. Ask any quote to separate these lines, and to state whether ongoing support is a retainer. The Collabora Online pricing page describes the Business plan as an annual per-user model, so confirm the billing period with Collabora before budgeting.

How do we restrict which applications can call the conversion API?

Restrict the API at the network layer and in Collabora's configuration. The Nextcloud administration manual describes restricting WOPI requests to known addresses, and Nextcloud previews need the Nextcloud host IP added to the net.post_allow.host allow list with coolconfig. Use a short, reviewed list, route callers through a gateway or private network where possible, and log every conversion request. Confirm the exact configuration keys for your Collabora version before you rely on them, because the names can change between branches.

Is the conversion output good enough for our documents?

Output quality depends on the source format, the fonts available on the server, and the target format. Collabora Online supports OpenDocument, docx, xlsx, pptx, PDF, RTF, CSV and Visio files, but fidelity differs by file. Build a test set from real documents, convert them to every target you need, and have business owners sign off on layout, tables, charts and fonts. Include the server's installed fonts in the test plan, since missing fonts are a common cause of visible differences.

Where to read the official conversion documentation

Start with the Collabora document conversion page, which covers the convert-to endpoint: an HTTP POST to /cool/convert-to/<format> on the coolwsd server, with the output format named in the path. It also compares the Collabora approach with JODConverter and unoconv, which is useful when you are deciding whether a conversion service should be built on Collabora Online at all. Read it for the supported output formats per document type (text, spreadsheet and presentation) and for the request shape. Then check the exact input formats and any parameters against your own server version, because the page describes behavior, and the behavior of a given branch is what your callers will meet. Confirm this with a test conversion of your own files before you build anything on top of it.

Next, read the Nextcloud admin manual section on Nextcloud Office configuration. It is the document to use when Nextcloud is the caller, since it explains how the Nextcloud host IP must be added to the net.post_allow.host allow list with coolconfig before the coolwsd conversion API can be used for previews. The same page covers restricting WOPI requests to known Collabora server addresses and matching the protocol of the Collabora server URL to the Nextcloud installation, which affects who can reach the conversion endpoint in the first place. Note that these settings govern the editing and preview paths in Nextcloud; a standalone caller such as a document pipeline needs its own allow-list entry and access review. Once you have both documents, the reading list for your team is the allow-list and access settings first, then the format tests on your own documents.

How DeployOpen scopes and delivers conversion services

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including cloud accounts, data centers and air-gapped networks. For a Collabora Online conversion service, that means agreeing the formats, callers and throughput targets in writing first, then building and handing over a service your team can operate.

How we scope

Engagements are fixed-scope, with the conversion formats, calling systems and deliverables agreed in writing before work starts.
We list every caller that will reach the conversion endpoint, such as Nextcloud preview generation, so the allow list is defined from the start.
We record the document types and sample files to convert, so output fidelity is tested against your real content, not a generic set.

How we build

We install Collabora Online in your environment and configure the net.post_allow.host entries with coolconfig for each approved caller.
We set up the convert-to requests, including PDF and image outputs, and test each supported input and output pair against the agreed list.
We run load tests at the concurrency you expect, then record the results so sizing decisions can be checked later.

How we hand over

You receive the configuration, the allow list with its owners, and runbooks for adding or removing a calling host.
Test results cover format fidelity and throughput, with notes on which conversions your team should recheck after each update.
Your staff are trained on operating the service, including reading logs and handling failed conversions.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer, covering Collabora Online updates and new callers.
Upgrades are retested against your format list before they reach production, so output changes are caught early.
Ask any partner, including DeployOpen, to confirm which Collabora Online branch and release channel they will support for you.

Collabora Online document conversion API