Tika Server (REST API)

curl -O https://downloads.apache.org/tika/4.1.0/tika-server-standard-4.1.0.zip
curl -O https://downloads.apache.org/tika/4.1.0/tika-server-standard-4.1.0.zip.sha512
shasum -a 512 tika-server-standard-4.1.0.zip      # compare with the .sha512 file
unzip -q -d tika-server-standard-4.1.0 tika-server-standard-4.1.0.zip
ls tika-server-standard-4.1.0

LICENSE  NOTICE  bin  lib  plugins  tika-server-standard-4.1.0.jar

cd tika-server-standard-4.1.0
java -jar tika-server-standard-4.1.0.jar --help

 usage:  tikaserver [-?] [-c <arg>] [-h <arg>] [-i <arg>] [--metricsPort
    <arg>] [-p <arg>]

       Options           Since                    Description
 -h, --host <arg>         --       host name (default = localhost, use * for
                                    all)
 -p, --port <arg>         --       listen port (default = 9998)
 -?, --help               --       this help message
 -c, --config <arg>       --       tika-config file
 -i, --id <arg>           --       id for this server, written to the startup
                                    log
 --metricsPort <arg>      --       serve Prometheus metrics on this port
                                   (9404 by convention); unset means metrics
                                    are off

{
  "server": {
    "host": "127.0.0.1",
    "port": 9998,
    "metricsPort": 9404,
    "endpoints": ["tika", "rmeta", "meta", "unpack", "detect", "language",
                  "parsers", "detectors", "mime-types", "version", "status"]
  },
  "pipes": {
    "numClients": 2,
    "forkedJvmArgs": ["-Xmx1g"]
  }
}

java -jar tika-server-standard-4.1.0.jar -c tika-config.json

INFO  TikaServerProcess Starting Apache Tika 4.1.0 server
INFO  TikaLoader temporary files go to java.io.tmpdir=/tmp
INFO  TikaServerProcess Using custom config: /opt/bookshelf/tika-config.json
INFO  TikaServerProcess Configuring __tika-server with basePath=/tmp/tika-server-input-...
INFO  TikaServerProcess Configuring __unpack with basePath=/tmp/tika-server-unpack-...
INFO  PipesParser Using per-client server mode with 2 clients
INFO  PerClientServerManager pipes-cpu-sizing: hostCores=8, numClients=2, parentReserved=2, autoCap=slice=3, heap=user-set in forkedJvmArgs
INFO  TikaServerProcess Pipes-based parsing enabled for /tika, /rmeta, /unpack, /meta, /detect, and /pipes endpoints
INFO  TikaServerProcess loading resource from SPI: class org.apache.tika.server.standard.resource.XMPMetadataResource
INFO  TikaServerProcess Started metrics listener (plain HTTP) on http://127.0.0.1:9404/metrics
INFO  TikaServerProcess Started Apache Tika server 61bd6b8b-ddc0-4db1-b274-865004226ef7 at http://127.0.0.1:9998/

docker run -d --name bookshelf-tika -p 127.0.0.1:9998:9998 apache/tika:4.1.0-1

# with your own configuration (paths inside the file are container paths)
docker run -d --name bookshelf-tika -p 127.0.0.1:9998:9998 \
  -v "$PWD/tika-config.json:/tika/config/tika-config.json:ro" \
  apache/tika:4.1.0-1 -c /tika/config/tika-config.json

curl -T manuscript.docx http://localhost:9998/tika          # Markdown, the 4.x default
curl -T manuscript.docx http://localhost:9998/tika/text     # body text only
curl -T catalogue.pdf   http://localhost:9998/tika/md

The Lighthouse Keeper

The Lighthouse Keeper

Chapter one begins at dusk.

The Lighthouse Keeper
Chapter one begins at dusk.

Spring catalogue

Bookshelf spring catalogue Forty titles from independent publishers.

curl -T manuscript.docx http://localhost:9998/tika/html

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="tk:content-type-parser-override" content="application/vnd.openxmlformats-officedocument.wordprocessingml.document">
<meta name="tk:content-type-magic-detected" content="application/x-tika-ooxml">
<meta name="dc:title" content="The Lighthouse Keeper">
<meta name="dc:creator" content="Ana Torres">
<meta name="Content-Length" content="1418">
<meta name="tk:parsed-by" content="org.apache.tika.parser.DefaultParser">
<meta name="tk:parsed-by" content="org.apache.tika.parser.microsoft.ooxml.OOXMLParser">
<meta name="Content-Type" content="application/vnd.openxmlformats-officedocument.wordprocessingml.document">
<title>The Lighthouse Keeper</title>
</head>
<body><p>The Lighthouse Keeper</p>
<p>Chapter one begins at dusk.</p>
</body></html>

curl -T manuscript.docx http://localhost:9998/tika/json

{
  "tk:content-type-parser-override": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "tk:content-type-magic-detected": "application/x-tika-ooxml",
  "dc:title": "The Lighthouse Keeper",
  "dc:creator": "Ana Torres",
  "tk:parsed-by-full-set": [
    "org.apache.tika.parser.DefaultParser",
    "org.apache.tika.parser.microsoft.ooxml.OOXMLParser"
  ],
  "zip:detector-zip-file-opened": "true",
  "tk:content": "The Lighthouse Keeper  \n\nThe Lighthouse Keeper\n\nChapter one begins at dusk.\n",
  "tk:parsed-by": [
    "org.apache.tika.parser.DefaultParser",
    "org.apache.tika.parser.microsoft.ooxml.OOXMLParser",
    "org.apache.tika.parser.microsoft.ooxml.xwpf.XWPFEventBasedWordExtractor"
  ],
  "Content-Length": "1418",
  "tk:content-handler-type": "MARKDOWN",
  "Content-Type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
}

curl -T publisher-email.eml \
  -H 'Content-Disposition: attachment; filename=publisher-email.eml' \
  http://localhost:9998/rmeta/text > rmeta.json
jq -r '.[] | [.["tk:embedded-depth"], .["Content-Type"], (.["tk:embedded-resource-path"] // "(container)")] | @tsv' rmeta.json

0	message/rfc822	(container)
3	image/png	/samples.zip/chapter-one.docx/figure1.png
2	application/vnd.openxmlformats-officedocument.wordprocessingml.document	/samples.zip/chapter-one.docx
2	application/pdf	/samples.zip/catalogue.pdf
2	text/plain; charset=windows-1252	/samples.zip/cover-note.txt
1	application/zip	/samples.zip

curl -T catalogue.pdf http://localhost:9998/meta                        # JSON object
curl -T catalogue.pdf -H 'Accept: text/csv' http://localhost:9998/meta  # key,value lines
curl -T catalogue.pdf -H 'Accept: application/rdf+xml' http://localhost:9998/meta   # XMP
curl -T catalogue.pdf http://localhost:9998/meta/dc:title               # one field

pdf:docinfo:title,Spring catalogue
pdf:incremental-update-count,0
pdf:has-xfa,false
dc:creator,Bookshelf Press
pdf:chars-per-page,67

{"dc:title":"Spring catalogue"}

curl -T renamed-invoice.png http://localhost:9998/detect
curl -T manuscript.docx http://localhost:9998/detect
curl -X PUT --data-binary @renamed-invoice.png \
  -H 'Content-Disposition: attachment; filename=renamed-invoice.png' http://localhost:9998/detect
curl -T empty.bin http://localhost:9998/detect

application/pdf
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/pdf
application/octet-stream

curl -s -T samples.zip http://localhost:9998/unpack -o unpack.zip && unzip -l unpack.zip
curl -s -T samples.zip http://localhost:9998/unpack/all -o unpack-all.zip && unzip -l unpack-all.zip
curl -s -i -T catalogue.pdf http://localhost:9998/unpack

  Length      Date    Time    Name
---------  ---------- -----   ----
     1926  10-12-2026 22:47   1.docx
      785  10-12-2026 22:47   2.pdf

  Length      Date    Time    Name
---------  ---------- -----   ----
     1329  10-12-2026 22:47   0.zip
      668  10-12-2026 22:47   0.zip.metadata.json
     1926  10-12-2026 22:47   1.docx
     1058  10-12-2026 22:47   1.docx.metadata.json
      785  10-12-2026 22:47   2.pdf
     1902  10-12-2026 22:47   2.pdf.metadata.json

HTTP/1.1 204 No Content

curl -T reviews-es.html http://localhost:9998/language
curl -T reseñas-fr.txt http://localhost:9998/language
curl -X POST -d 'The catalogue lists forty titles.' http://localhost:9998/language

es
fr
en

curl -H 'Accept: text/plain' http://localhost:9998/parsers | head -4
curl -H 'Accept: application/json' http://localhost:9998/mime-types/application/pdf
curl http://localhost:9998/version
curl http://localhost:9998/status

org.apache.tika.parser.DefaultParser (Composite Parser):
  org.apache.tika.parser.apple.AppleSingleFileParser
  org.apache.tika.parser.apple.PListParser
  org.apache.tika.parser.asm.ClassParser

{
  "extensions" : [ ".pdf" ],
  "parser" : "org.apache.tika.parser.pdf.PDFParser",
  "acronym" : "PDF",
  "alias" : [ "application/x-pdf" ],
  "description" : "Portable Document Format",
  "uniformTypeIdentifier" : "com.adobe.pdf",
  "links" : [ "http://en.wikipedia.org/wiki/PDF", "http://www.adobe.com/devnet/pdf/pdf_reference_archive.html" ],
  "type" : "application/pdf",
  "defaultExtension" : ".pdf"
}

Apache Tika 4.1.0

{
  "status" : "OPERATING",
  "active_tasks" : 0,
  "millis_since_last_parse_started" : 4623,
  "files_processed" : 26
}

curl -i -X POST http://localhost:9998/pipes -H 'Content-Type: application/json' -d '{
  "id": "cat-1",
  "fetcher": "bookshelf-in",
  "fetchKey": "catalogue.pdf",
  "emitter": "bookshelf-out",
  "emitKey": "catalogue"
}'

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status" : "EMIT_SUCCESS"
}

curl -i -X POST http://localhost:9998/async -H 'Content-Type: application/json' -d '{"tuples":[
  {"id":"ms","fetcher":"bookshelf-in","fetchKey":"manuscript.docx","emitter":"bookshelf-out","emitKey":"manuscript"},
  {"id":"ep","fetcher":"bookshelf-in","fetchKey":"novel.epub","emitter":"bookshelf-out","emitKey":"novel"}]}'

HTTP/1.1 200 OK
Content-Type: application/json

{
  "added" : 2,
  "status" : "ok"
}

curl -i -T catalogue.pdf http://localhost:9998/tika/text

HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json
Content-Length: 41

{"status":"CLIENT_UNAVAILABLE_WITHIN_MS"}

curl -i -T huge-catalogue.txt http://localhost:9998/tika/text

HTTP/1.1 503 Service Unavailable
Retry-After: 5
Content-Type: application/json
Content-Length: 406

{"status":"TIMEOUT","message":"java.lang.RuntimeException\n\tat org.apache.tika.pipes.core.server.PipesServer.checkProgressTimeout(PipesServer.java:699)\n\tat org.apache.tika.pipes.core.server.PipesServer.loopUntilDone(PipesServer.java:669)\n\t..."}

{
  "parse-context": {
    "exception-reporting": { "level": "MESSAGE_REDACTED", "maxLength": 2000 }
  }
}

package org.example.bookshelf;

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;
import java.time.Duration;

public class TikaHttpClientExample {

    private static final URI TIKA = URI.create(
            System.getenv().getOrDefault("TIKA_URL", "http://127.0.0.1:9998"));
    private static final int MAX_ATTEMPTS = 5;

    private final HttpClient http = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .build();

    /** PUTs one file to /tika/text and returns the body text. */
    public String extractText(Path file) throws IOException, InterruptedException {
        HttpRequest request = HttpRequest.newBuilder(TIKA.resolve("/tika/text"))
                .timeout(Duration.ofMinutes(5))
                .header("Content-Disposition",
                        "attachment; filename=" + file.getFileName())
                .PUT(HttpRequest.BodyPublishers.ofFile(file))
                .build();

        for (int attempt = 1; ; attempt++) {
            HttpResponse<String> response =
                    http.send(request, HttpResponse.BodyHandlers.ofString());
            int status = response.statusCode();
            switch (status) {
                case 200:
                    return response.body();
                case 204:
                    return "";
                case 422:
                    // the document threw, but this is what was extracted before it did
                    System.err.println("partial parse of " + file);
                    return response.body();
                case 429:
                    if (attempt == MAX_ATTEMPTS) {
                        throw new IOException("tika-server still busy after "
                                + attempt + " attempts");
                    }
                    long waitSeconds = response.headers()
                            .firstValueAsLong("Retry-After").orElse(2L);
                    Thread.sleep(Duration.ofSeconds(waitSeconds));
                    break;
                case 503:
                    // a fork crashed, ran out of memory or timed out on THIS document:
                    // do not loop on it, hand it to a dead-letter queue instead
                    throw new IOException("fork failed on " + file + ": " + response.body());
                default:
                    throw new IOException("HTTP " + status + " for " + file + ": "
                            + response.body());
            }
        }
    }

    public static void main(String[] args) throws Exception {
        TikaHttpClientExample client = new TikaHttpClientExample();
        for (String name : args) {
            System.out.println("--- " + name);
            System.out.println(client.extractText(Path.of(name)).strip());
        }
    }
}

TIKA_URL=http://127.0.0.1:9998 java -cp target/classes \
  org.example.bookshelf.TikaHttpClientExample manuscript.docx catalogue.pdf

--- manuscript.docx
The Lighthouse Keeper
Chapter one begins at dusk.
--- catalogue.pdf
Bookshelf spring catalogue
Forty titles from independent publishers.

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-web</artifactId>
  <version>7.0.9</version>
</dependency>

dependencies {
    implementation("org.springframework:spring-web:7.0.9")
}

package org.example.bookshelf;

import java.nio.file.Path;
import java.time.Duration;

import org.springframework.core.io.FileSystemResource;
import org.springframework.http.ContentDisposition;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.client.JdkClientHttpRequestFactory;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.client.RestClient;

public class TikaRestClientExample {

    private final RestClient tika;

    public TikaRestClientExample(String baseUrl) {
        JdkClientHttpRequestFactory factory = new JdkClientHttpRequestFactory();
        factory.setReadTimeout(Duration.ofMinutes(5));
        this.tika = RestClient.builder()
                .baseUrl(baseUrl)
                .requestFactory(factory)
                .build();
    }

    /** PUT the raw bytes to /rmeta/text: one JSON object per document, embedded ones included. */
    public String recursiveMetadata(Path file) {
        return tika.put()
                .uri("/rmeta/text")
                .contentType(MediaType.APPLICATION_OCTET_STREAM)
                .headers(h -> h.setContentDisposition(ContentDisposition.attachment()
                        .filename(file.getFileName().toString()).build()))
                .body(new FileSystemResource(file))
                .retrieve()
                .onStatus(s -> s.value() == HttpStatus.TOO_MANY_REQUESTS.value(), (req, res) -> {
                    String retryAfter = res.getHeaders().getFirst("Retry-After");
                    throw new IllegalStateException("busy, retry after " + retryAfter + "s");
                })
                .onStatus(s -> s.value() == HttpStatus.SERVICE_UNAVAILABLE.value(), (req, res) -> {
                    throw new IllegalStateException("fork failed on " + file);
                })
                .body(String.class);
    }

    /** Multipart POST to /rmeta/form/text: the browser-style upload, no per-request config. */
    public String recursiveMetadataMultipart(Path file) {
        MultiValueMap<String, Object> parts = new LinkedMultiValueMap<>();
        parts.add("file", new FileSystemResource(file));
        return tika.post()
                .uri("/rmeta/form/text")
                .contentType(MediaType.MULTIPART_FORM_DATA)
                .body(parts)
                .retrieve()
                .body(String.class);
    }

    public static void main(String[] args) {
        TikaRestClientExample client = new TikaRestClientExample(
                System.getenv().getOrDefault("TIKA_URL", "http://127.0.0.1:9998"));
        Path email = Path.of(args[0]);
        String put = client.recursiveMetadata(email);
        String multipart = client.recursiveMetadataMultipart(email);
        System.out.println("PUT  /rmeta/text      -> " + put.length() + " chars, "
                + (put.split("\"tk:embedded-depth\"").length - 1) + " documents");
        System.out.println("POST /rmeta/form/text -> " + multipart.length() + " chars");
        System.out.println(put.substring(0, Math.min(160, put.length())));
    }
}

PUT  /rmeta/text      -> 8187 chars, 6 documents
POST /rmeta/form/text -> 8187 chars
[{"tk:content-type-parser-override":"message/rfc822","message:from-name":"Marta Ruiz","message:raw-header:Message-ID":"<spring-samples-1@press.example>","multip

<!-- Tika 3.x only -->
<properties>
  <server>
    <params>
      <port>9998</port>
      <enableUnsecureFeatures>true</enableUnsecureFeatures>
      <taskTimeoutMillis>300000</taskTimeoutMillis>
      <forkedJvmArgs>
        <arg>-Xmx2g</arg>
      </forkedJvmArgs>
      <endpoints>
        <endpoint>rmeta</endpoint>
        <endpoint>pipes</endpoint>
        <endpoint>status</endpoint>
      </endpoints>
    </params>
  </server>
</properties>

{
  "server": {
    "port": 9998,
    "allowPipes": true,
    "endpoints": ["rmeta", "pipes", "status"]
  },
  "pipes": {
    "forkedJvmArgs": ["-Xmx2g"]
  },
  "parse-context": {
    "timeout-limits": { "totalTaskTimeoutMillis": 300000 }
  }
}