Skip to content
OfficePDF
REST API v1 · on-prem and cloud

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.

Base URL (on-prem default)
http://localhost:8080/v1
Base URL (cloud API)
https://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/pdf

Deploy 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.

PowerShell
# 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 serve runs in the foreground for debugging; officepdf-server install-service registers the OfficePDFServer Windows service, which starts with Windows (requires Administrator).
  • By default it listens on 127.0.0.1:8080 with 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/health returns the engine version, license expiry and queue depth without authentication — handy for monitoring. Interactive API docs live at http://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.

OptionEnvironment variableDefaultMeaning
--hostOFFICEPDF_HOST127.0.0.1Bind address; non-loopback addresses require an API key
--portOFFICEPDF_PORT8080Port
--api-keyOFFICEPDF_API_KEY—When set, every endpoint except health requires this key
--licenseOFFICEPDF_LICENSE_FILE%PROGRAMDATA%\OfficePDF\officepdf.licPath to the license file
--data-dirOFFICEPDF_DATA_DIR./dataWhere PDFs and diagnostics reports are stored
--workersOFFICEPDF_WORKERS2Concurrent conversions
--timeoutOFFICEPDF_TIMEOUT120Per-document timeout in seconds
--retention-daysOFFICEPDF_RETENTION_DAYS7Days to keep results before automatic deletion
—OFFICEPDF_MAX_UPLOAD_MB20Maximum 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.

officepdf-lic_xxx.lic
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.

Public key / online check
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.

LanguagePackageRequires
PythonofficepdfPyPIPython 3.9+
Node.js@officepdf/sdknpmNode.js 18+
C# / .NETOfficePDF.SdkNuGet.NET Framework 4.6.1+ / .NET 8
Javacom.getofficepdf:officepdf-sdkMaven CentralJava 8+
pip install officepdf
  • convert() 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 rejected and read error.
  • Diagnostics are objects with page numbers and can be filtered by severity, page or code; needs_review flags 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_URL and OFFICEPDF_API_KEY in the environment.
On-prem or cloud (Python)
client = OfficePDF(base_url="http://localhost:8080")   # on-prem service
client = OfficePDF(api_key="opk_your_key")              # Cloud API

Authentication

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.

HTTP
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.

POST /v1/conversions
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.

202 Accepted
{
  "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.

GET /v1/conversions/{id}
curl http://localhost:8080/v1/conversions/job_123
StatusMeaningBilled (cloud)
queuedAccepted and waiting to be processed.No
runningBeing converted.No
succeededDone — the PDF is ready to download.Yes
rejectedStrict mode found content it can't render correctly. See error and diagnostics.No
failedThe conversion failed (for example a corrupt file). See error.No
cancelledCancelled.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.

GET /v1/conversions/{id}/pdf
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.

GET /v1/conversions/{id}/report
curl http://localhost:8080/v1/conversions/job_123/report

List 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.

GET /v1/conversions
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.

DELETE /v1/conversions/{id}
curl -X DELETE http://localhost:8080/v1/conversions/job_123

Errors

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.

JSON
HTTP/1.1 415 Unsupported Media Type
{
  "error": {
    "code": "unsupported_format",
    "message": "Only .docx and .doc documents are supported."
  }
}
codeHTTPMeaning
unauthorized401No credentials were provided.
invalid_api_key401The API key is invalid or revoked.
session_requiredcloud only403This endpoint only accepts a signed-in browser session.
email_unverifiedcloud only403The account's email is not verified.
account_disabledcloud only403The account is disabled.
quota_exhaustedcloud only402No pages left; buy a page pack.
unsupported_format415Not a .docx/.doc file, or the content doesn't match the extension.
file_too_large413The file is larger than 20 MB.
validation_error422Invalid request parameters; see details.
too_many_active_jobs429More than 20 queued or running jobs.
rate_limitedcloud only429Too many requests; back off and retry.
job_not_found404The job doesn't exist or belongs to another account.
not_ready409The job hasn't succeeded yet; no output.
expired410The 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.
  • .docx is supported; legacy .doc is 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.

Base URL (cloud API)
https://api.getofficepdf.com/v1
ItemOn-prem serviceCloud API
AuthenticationNone by default; --api-key when serving the networkAPI key starting with opk_ required
Billingbilled_pages is always 0, unlimited pagesBilled per successfully converted page
channel fieldonpremapi
Parallel jobsSet by --workersUp to 20 per account
DataOnly on your own serversPDFs 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"