Tika Server

/tika/config, /tika/config/{text,html,xml,md,json}, /rmeta/config and /meta/config accept a caller-supplied parser configuration as a multipart config part. They do not reveal the server’s own config, but a caller-supplied one can enable dangerous operations such as pointing parsers at attacker-chosen resources (see CVE-2015-3271). They are disabled by default; a request to one is rejected with 403.

There is no CLI flag — set allowPerRequestConfig in the server section:

/pipes and /async drive process-isolated batch parsing through your configured fetchers and emitters, so whoever can reach them gains the read access of your fetchers and the write access of your emitters (again CVE-2015-3271). Listing them under endpoints is not enough — without allowPipes the server refuses to start, deliberately making this an explicit choice:

Simple PUT — the entire request body is the document, no metadata:

POST with multipart for custom per-request configuration:

Valid handler paths under /tika/: text, html, xml, md, json (bare /tika returns Markdown). For the JSON variant, nest a handler — /tika/json/text, /tika/json/html, …​ — to choose the content-field format inside the JSON envelope; that nested handler accepts the full set (text, txt, html, xml, body, markdown, md, ignore).

Returns metadata for the container document and all embedded documents as a JSON array of metadata objects. The handler controls the content field of each entry:

Returns container-document metadata only — no recursive embedded list, no content. With no Accept header it returns JSON; request text/csv or application/rdf+xml for the other representations.

PUT the bytes; the response is the media type as text/plain. A Content-Disposition filename is an optional hint — detection is driven by the bytes, so it works without one.

The endpoints config name is what you list under server.endpoints; leaving endpoints unset enables everything below except status, which is opt-in and must be listed explicitly. pipes and async are part of that default set too, but only when allowPipes=true — with allowPipes left at its false default they are not served at all.

When the fork times out, runs out of memory, or crashes, the server returns an HTTP error whose JSON body carries the PipesResult.RESULT_STATUS enum name, plus a message field when one is available (often a server-side stack trace):

Here the fork ran to completion and simply caught an exception on this one document (an encrypted file with no password, a malformed embedded object, an NPE in a specific parser). The fork is healthy, and whatever content it extracted is still available. The status depends on whether the response shape has room to embed the exception alongside content:

A third case is neither of the above: the fork is healthy and no exception was caught, but the document’s total task timeout (totalTaskTimeoutMillis) ran out partway through, so not-yet-started embedded documents were skipped rather than attempted. PARTIAL_TIMEOUT maps to 200 OK on every endpoint — it is a success, just an incomplete one — alongside PARSE_SUCCESS, PARSE_SUCCESS_WITH_EXCEPTION, etc. The response carries TikaCoreProperties.TASK_DEADLINE_REACHED = true and whatever content was extracted before the deadline. See How Timeouts Are Reported for the full mental model, including the pipes-mode throwOnDeadline option that trades this graceful truncation for a hard failure.

Each group holds a fixed pool of numClients forks. A request that arrives when all are busy waits up to pipes.maxWaitForClientMillis (default 60s) for one to free up. This is deliberate backpressure: if a fork frees up in time the request is served normally; if the wait times out the server returns 429 with status: CLIENT_UNAVAILABLE_WITHIN_MS — an explicit "I’m at capacity, retry", not a crash (see Error Responses).

CLIENT_UNAVAILABLE_WITHIN_MS under real load means this group is undersized for your request volume: raise numClients for more concurrent capacity, or tune maxWaitForClientMillis to fail faster (surface backpressure sooner) or more patiently (absorb bursts, at the cost of tying up request threads while waiting).

Independently, each group auto-sizes its forked JVMs' -XX:ActiveProcessorCount from numClients and the host’s core count — see Forked-JVM CPU and Heap Sizing for the mechanics.

This part can go wrong across groups: one group’s auto-sizer has no visibility into the other group in the same process. Enable /async alongside the shared group — by listing async together with any of tika/rmeta/unpack/meta/detect/pipes, or simply by leaving endpoints unset with allowPipes=true — and each group computes its slice as if it owned the whole host. Whether that oversubscribes depends on your numClients values relative to the core count; it is not automatic, but the auto-sizer will not warn you either, because from within either group the sizing looks fine. See Known limitation: multiple Pipes groups in one process for the mitigation (scope endpoints to what you use, or set -XX:ActiveProcessorCount explicitly with the combined total in mind).