Skip to main content
Start the container without positional arguments and FineParser runs as an HTTP server on port 8080. It stays up until you stop it. Use this mode when your applications or other services need to send documents to FineParser over the network.
Recognition mode, languages, and the license are all set when the container starts, so requests carry no credentials or recognition settings. Results are written to /app/output, so mount a volume there or they disappear with the container. See Configuration.

How a parse works

Parsing is asynchronous. You submit a document and get a job ID back immediately, poll the job until it settles, then download the result. Recognition happens on a single worker inside the container, one document at a time, so the HTTP connection is never held open for the length of a recognition.
1

Submit

POST /parse with the document and an output type. The response is 202 Accepted with the job ID.
2

Poll

GET /jobs/{id} until status is successful, failed, or cancelled.
3

Download

GET /jobs/{file}, where file is the path the status response reports. The result streams back as an attachment.

Endpoints

Every error response is JSON with an error field that describes the problem. Some carry a code or status field as well, noted below.

POST /parse

Submit one document. Send it as multipart/form-data with a file field holding the document and an outputType field set to doclang, json, or txt. See Output formats. A successful submission returns 202 Accepted, a Location header pointing at the job, and a body with the job ID and the filename FineParser recorded.
The licensing check happens before any of the upload is read, so an unlicensed container refuses without spending bandwidth or disk on the request.

GET /jobs/{id}

Report a job’s state.
file is the result’s path in the form {jobId}/{name}. Prefix it with /jobs/ to get the download URL. The name is the uploaded filename with the output type appended, so document.pdf parsed to DocLang becomes document.pdf.doclang. The field is absent until the job succeeds, and disappears again if the result is removed from disk. A job can fail for licensing reasons after it was accepted, because the page count is only known once the document is loaded. In that case status is failed and error says so. Nothing is charged for a failed job. Returns 404 if there is no such job.

GET /jobs/{id}/{name}

Download a result. Use the file value from the status response as the path. The result streams back with a Content-Type matching the output format and a Content-Disposition attachment header naming the file, so curl -OJ saves it under the right name. Ranged requests are not served.

DELETE /jobs/{id}

Remove a job and its result from disk.

GET /healthz

Report whether the container is licensed and ready to accept documents. Use it as the readiness probe in Kubernetes or your orchestrator. The container image also runs it as its own Docker HEALTHCHECK.
A ready container returns 200. An unready one returns 503 with ready: false, a code explaining why, and usually a detail message. Readiness reflects licensing only. Telemetry is reported alongside it and never affects it. See Confirming the license.

Results on disk

Every result is written under /app/output as {jobId}/{name}, next to a small job database. The layout is stable, so you can also collect results straight from the mounted volume instead of downloading them over HTTP. By default a result stays until you DELETE the job or clear it from the volume yourself. Nothing expires by age. If you would rather have FineParser clean up, start the container with DELETE_ON_DOWNLOAD=true and each result is removed, along with its job record, as soon as it has been downloaded in full. After that both the status and the download return 404. An interrupted download leaves the result in place for a retry. Uploads are held in a separate scratch directory and deleted as soon as recognition finishes, whichever way it went.

Restarts and shutdown

Jobs are recorded in the job database on the output volume, so they survive a restart as long as the volume does. Pending jobs are picked up again. A job that was in progress when the process died is marked failed, because the process cannot know how much of the result was written. On a clean stop, FineParser stops accepting requests, lets in-flight requests finish, and exits without waiting for the document being recognized. Recognition cannot be interrupted, and waiting for it could hold the shutdown open for minutes. That job is marked cancelled and its partial result is removed. Resubmit it if you still want it. Give the container a stop timeout of 60 seconds, with --stop-timeout 60 in Docker or terminationGracePeriodSeconds: 60 in Kubernetes. Docker’s default of 10 seconds cuts the drain short and loses the usage telemetry for everything since the last export. Only one container can use a given output directory at a time. The job database is locked while open, so a second container on the same volume refuses to start. Two containers need two volumes.