Documentation
The OfficePDF on-prem service runs on your own Windows servers and exposes a small REST API: upload a Word document, poll its status, download the PDF. The cloud API is exactly the same interface with a different address and authentication. This page covers deployment and licensing first, then the API.
Need every field explained? See the interactive API reference (OpenAPI).
Quick start
Conversions are asynchronous: submit a document with POST /v1/conversions, poll its status every 1–2 seconds with the returned job ID, and download the PDF once it is succeeded. The samples below target the local on-prem service; for the cloud API, swap in the cloud base URL and add your API key. All requests and responses are JSON (except uploads) and all timestamps are ISO-8601 in UTC.
http://localhost:8080/v1https://api.getofficepdf.com/v1# 1. Upload a document (strict mode is the default)
curl -X POST http://localhost:8080/v1/conversions \
-F "[email protected]" -F "mode=strict"
# => {"id": "job_...", "status": "queued", ...}
# 2. Poll until status is final
curl http://localhost:8080/v1/conversions/job_123
# 3. Download the PDF
curl -o report.pdf http://localhost:8080/v1/conversions/job_123/pdfDeploy the on-prem service
The on-prem service ships as a self-contained package that runs on 64-bit Windows Server without installing Python. With an active license (including an evaluation license), download the package and license file from Licenses & downloads in the dashboard.
# Run as Administrator
# 1. License file: verified locally, no phone-home
$dir = "$env:ProgramData\OfficePDF"
New-Item -ItemType Directory -Force $dir | Out-Null
Copy-Item .\officepdf-lic_xxx.lic "$dir\officepdf.lic"
# 2. Install and start the service (127.0.0.1:8080)
officepdf-server install-service --port 8080
sc.exe start OfficePDFServer
# 3. Engine version, license expiry, queue depth
curl.exe http://localhost:8080/v1/health
# Serving other machines requires an API key:
# officepdf-server install-service --host 0.0.0.0 --api-key <secret>officepdf-server serveruns in the foreground for debugging;officepdf-server install-serviceregisters theOfficePDFServerWindows service, which starts with Windows (requires Administrator).- By default it listens on
127.0.0.1:8080with no authentication. To listen on other addresses (e.g.--host 0.0.0.0) you must also set--api-key, otherwise the service refuses to start — so nobody else on the network can download PDFs converted by others. - The Windows service runs under a system account and can't see fonts installed for a single user. Install the fonts your documents use "for all users".
GET /v1/healthreturns the engine version, license expiry and queue depth without authentication — handy for monitoring. Interactive API docs live athttp://localhost:8080/docs.
Startup options
Every option can be set on the command line or through an OFFICEPDF_* environment variable, so the Windows service needs no config file.
| Option | Environment variable | Default | Meaning |
|---|---|---|---|
| --host | OFFICEPDF_HOST | 127.0.0.1 | Bind address; non-loopback addresses require an API key |
| --port | OFFICEPDF_PORT | 8080 | Port |
| --api-key | OFFICEPDF_API_KEY | — | When set, every endpoint except health requires this key |
| --license | OFFICEPDF_LICENSE_FILE | %PROGRAMDATA%\OfficePDF\officepdf.lic | Path to the license file |
| --data-dir | OFFICEPDF_DATA_DIR | ./data | Where PDFs and diagnostics reports are stored |
| --workers | OFFICEPDF_WORKERS | 2 | Concurrent conversions |
| --timeout | OFFICEPDF_TIMEOUT | 120 | Per-document timeout in seconds |
| --retention-days | OFFICEPDF_RETENTION_DAYS | 7 | Days to keep results before automatic deletion |
| — | OFFICEPDF_MAX_UPLOAD_MB | 20 | Maximum file size in MB (environment variable only) |
License file and offline verification
License file
After evaluation or purchase you get a license file (.lic) in the dashboard: a single line starting with OPDF1., made of the license payload (customer, edition, features, server count, expiry) and an Ed25519 signature. It lives at %PROGRAMDATA%\OfficePDF\officepdf.lic by default, or pass --license.
OPDF1.eyJpZCI6ImxpY18uLi4iLCJjdXN0b21lciI6Ii4uLiJ9.MEUCIQ...Offline verification
The on-prem service embeds OfficePDF's Ed25519 public key and checks the signature and expiry locally at startup — no connection to our servers. The public key is also available from the cloud at GET /v1/licenses/public-key; if the server has internet access you can call POST /v1/licenses/verify to check whether a license was revoked.
curl https://api.getofficepdf.com/v1/licenses/public-key
curl -X POST https://api.getofficepdf.com/v1/licenses/verify \
-H "Content-Type: application/json" \
-d '{"license": "OPDF1...."}'
# => { "valid": true, "problem": null, "payload": { ... } }Official SDKs
Official client libraries for Python, Node.js, .NET and Java are published to each ecosystem's standard registry, all MIT-licensed. Each one uploads, polls and downloads in a single call, and works with both the on-prem service and the cloud API.
| Language | Package | Requires |
|---|---|---|
| Python | officepdfPyPI | Python 3.9+ |
| Node.js | @officepdf/sdknpm | Node.js 18+ |
| C# / .NET | OfficePDF.SdkNuGet | .NET Framework 4.6.1+ / .NET 8 |
| Java | com.getofficepdf:officepdf-sdkMaven Central | Java 8+ |
pip install officepdfconvert()uploads the document, polls with backoff and returns the final result — no polling loop to write.- A strict-mode rejection is a normal result, not an exception: check
rejectedand readerror. - Diagnostics are objects with page numbers and can be filtered by severity, page or code;
needs_reviewflags PDFs produced with fallbacks. - Switching between the on-prem service and the cloud is just a base URL change (plus an API key for the cloud). You can also configure
OFFICEPDF_BASE_URLandOFFICEPDF_API_KEYin the environment.
client = OfficePDF(base_url="http://localhost:8080") # on-prem service
client = OfficePDF(api_key="opk_your_key") # Cloud APIAuthentication
The on-prem service listens on localhost only and needs no authentication by default; once --api-key is set, every request must carry that key. Every cloud API endpoint requires an API key starting with opk_. Both use a Bearer token in the request header.
Authorization: Bearer opk_your_key
# or use the X-API-Key header
X-API-Key: opk_your_key- A key is shown in full only once, when it is created. Store it in server-side configuration — never in frontend code or a repository.
- Cloud: each account can have up to 20 active keys at a time. Revoked keys stop working immediately and return
invalid_api_key. - Cloud: create and revoke keys on the API keys page in the dashboard. Account management endpoints (purchases, creating keys) only accept a signed-in browser session; calling them with an API key returns
session_required.
Create a conversion
Upload as multipart/form-data with the document in the file field (.docx or .doc, up to 20 MB by default) and mode set to strict (default) or preview.
curl -X POST http://localhost:8080/v1/conversions \
-F "[email protected]" \
-F "mode=strict"A successful submission returns 202 Accepted with the job object in status queued. The on-prem service has no page limit; a cloud account needs a verified email and remaining pages, otherwise you get email_unverified or quota_exhausted.
{
"id": "job_8f2c1d...",
"status": "succeeded",
"degraded": false,
"filename": "report.docx",
"input_format": "docx",
"mode": "strict",
"pages": 12,
"billed_pages": 12,
"error": null,
"diagnostics": [
{ "code": "font_substituted", "severity": "info", "message": "...", "page": 3 }
],
"diagnostics_total": 1,
"engine_version": "1.4.0",
"created_at": "2026-10-07T08:00:00Z",
"finished_at": "2026-10-07T08:00:04Z",
"expires_at": "2026-10-14T08:00:04Z",
"output_available": true,
"pdf_url": "/v1/conversions/job_8f2c1d.../pdf"
}Strict and preview modes
Both modes use the same engine. They differ in how content that can't be rendered correctly is handled.
strict
The default. If the document contains anything the engine can't guarantee (for example an unsupported equation), the job ends as rejected with a reason. No PDF is produced and no pages are billed. Use it for contracts, official documents and invoices.
preview
Always tries to produce a PDF. Unsupported content falls back (for example to a placeholder), the job's degraded flag is true, and the diagnostics report marks each fallback. Use it for previews or archiving where small deviations are acceptable.
Get status
Fetch the job with GET /v1/conversions/{id}. Poll every 1–2 seconds until the status is no longer queued or running.
curl http://localhost:8080/v1/conversions/job_123| Status | Meaning | Billed (cloud) |
|---|---|---|
| queued | Accepted and waiting to be processed. | No |
| running | Being converted. | No |
| succeeded | Done — the PDF is ready to download. | Yes |
| rejected | Strict mode found content it can't render correctly. See error and diagnostics. | No |
| failed | The conversion failed (for example a corrupt file). See error. | No |
| cancelled | Cancelled. | No |
When status is succeeded and degraded is true, some content fell back in preview mode; check diagnostics to decide whether the output is acceptable. The job carries up to 50 diagnostics (diagnostics_total has the full count); fetch the report for all of them.
Download the PDF
Once succeeded, download with GET /v1/conversions/{id}/pdf (application/pdf). Results are kept for 7 days; afterwards you get 410 expired. Before success you get 409 not_ready.
curl -o contract.pdf http://localhost:8080/v1/conversions/job_123/pdf
# open in the browser instead of downloading
curl "http://localhost:8080/v1/conversions/job_123/pdf?disposition=inline"Diagnostics report
GET /v1/conversions/{id}/report returns the full engine report: page count, all diagnostics (up to 200, each with code, severity, message and page), the font manifest and file hashes. Available as soon as a job finishes — including rejected and failed jobs.
curl http://localhost:8080/v1/conversions/job_123/reportList conversions
GET /v1/conversions returns jobs newest first. It accepts limit (1–100, default 20), a status filter and cursor pagination: when has_more is true, pass next_cursor as cursor in the next request.
curl "http://localhost:8080/v1/conversions?limit=20&status=succeeded"
# => { "data": [...], "has_more": true, "next_cursor": "job_..." }
curl "http://localhost:8080/v1/conversions?limit=20&cursor=job_..."Cancel and delete
DELETE /v1/conversions/{id} cancels a queued or running job (not billed). For a finished job it deletes the stored PDF and report immediately; the job record is kept for accounting.
curl -X DELETE http://localhost:8080/v1/conversions/job_123Errors
Every error uses the same shape, {"error": {"code", "message"}}. Branch on code; message is for humans and may change. Validation errors also include a details list. Errors marked "cloud only" relate to accounts and quota and are never returned by the on-prem service.
HTTP/1.1 415 Unsupported Media Type
{
"error": {
"code": "unsupported_format",
"message": "Only .docx and .doc documents are supported."
}
}| code | HTTP | Meaning |
|---|---|---|
| unauthorized | 401 | No credentials were provided. |
| invalid_api_key | 401 | The API key is invalid or revoked. |
| session_requiredcloud only | 403 | This endpoint only accepts a signed-in browser session. |
| email_unverifiedcloud only | 403 | The account's email is not verified. |
| account_disabledcloud only | 403 | The account is disabled. |
| quota_exhaustedcloud only | 402 | No pages left; buy a page pack. |
| unsupported_format | 415 | Not a .docx/.doc file, or the content doesn't match the extension. |
| file_too_large | 413 | The file is larger than 20 MB. |
| validation_error | 422 | Invalid request parameters; see details. |
| too_many_active_jobs | 429 | More than 20 queued or running jobs. |
| rate_limitedcloud only | 429 | Too many requests; back off and retry. |
| job_not_found | 404 | The job doesn't exist or belongs to another account. |
| not_ready | 409 | The job hasn't succeeded yet; no output. |
| expired | 410 | The output passed its retention period and was deleted. |
Limits
On the on-prem service, file size, concurrency, timeouts and retention are set by the startup options, and pages are unlimited. The limits below apply to the cloud API.
- Maximum file size: 20 MB.
.docxis supported; legacy.docis experimental and best used with preview mode.- Up to 20 queued or running jobs per account; beyond that you get
too_many_active_jobs. - Source files are deleted right after conversion; PDFs and reports are kept for 7 days and can be deleted earlier with DELETE.
- Login, sign-up and password-reset endpoints are rate-limited per IP and return
429 rate_limited; retry with exponential backoff.
Cloud API
If you'd rather not run it yourself, use our hosted cloud API: same interface as the on-prem service, billed per successfully converted page, with free trial pages once you verify your email.
https://api.getofficepdf.com/v1| Item | On-prem service | Cloud API |
|---|---|---|
| Authentication | None by default; --api-key when serving the network | API key starting with opk_ required |
| Billing | billed_pages is always 0, unlimited pages | Billed per successfully converted page |
| channel field | onprem | api |
| Parallel jobs | Set by --workers | Up to 20 per account |
| Data | Only on your own servers | PDFs and reports kept 7 days |
# 1. Upload a document (strict mode is the default)
curl -X POST https://api.getofficepdf.com/v1/conversions \
-H "Authorization: Bearer opk_your_key" \
-F "[email protected]" -F "mode=strict"
# => {"id": "job_...", "status": "queued", ...}
# 2. Poll until status is final
curl https://api.getofficepdf.com/v1/conversions/job_123 \
-H "Authorization: Bearer opk_your_key"
# 3. Download the PDF
curl -o report.pdf https://api.getofficepdf.com/v1/conversions/job_123/pdf \
-H "Authorization: Bearer opk_your_key"