Tika Server

/tika/config, /tika/config/{text,html,xml,md,json}, /rmeta/config, /rmeta/config/{handlerType} 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:

A preset is a named, vetted parse-context fragment: parser and component configurations keyed by friendly name, defined once in the server config (or shipped with Tika) and selected whole by name. Callers apply one by inserting preset/{name} directly after the resource root: /tika/preset/{name}[/text|/html|/xml|/md|/json[/{handlerType}]], /rmeta/preset/{name}[/{handlerType}], /unpack/preset/{name}[/all].

Nothing is active unless the top-level presets key names it. true activates a preset from the classpath catalog (definitions shipped with Tika, so their content tracks the Tika version); an object defines a preset in place, replacing any same-named catalog definition wholesale; false/null is an explicit no-op. Catalog jars can never activate themselves — every active preset is a visible line in the operator’s config, and true naming nothing in the catalog fails startup:

Presets are deliberately narrow: a request selects exactly one, the preset routes take no config part, and a preset never combines with request-supplied configuration — a variant is another preset. Because preset content is operator- or Tika-vetted, the preset routes do not require allowPerRequestConfig, and the preset/{name} path segment gives network controls an addressable surface — a reverse proxy can allow /rmeta/preset/ while blocking /rmeta/config entirely. An unknown preset name answers 404. Names are letters, digits, ., _, - (max 100 chars) and may not start with config (that path fragment gates the /config endpoints).

Only the preset’s name travels with a request: the forked parse worker resolves the content from its own copy of the server config, with the same trust as the config’s own parse-context block. A preset can therefore bind components per-request /config input may not (detectors, embedded-document extraction, exception reporting, …​) and raise timeout limits above the per-request clamp. Every active preset resolves at startup, so a bad preset fails the server, not its first request.

/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:

POST with multipart for per-request configuration; the handler goes in the path, not the config part:

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