Queries using the REST API
The examples below use the default credentials (odilon:odilon) and port 9234. Adjust them to your
installation. Special characters in URLs must be percent-encoded (%2A = *, %22 =
", %3F = ?).
Lucene based queries: GET /search
Parameters (all optional):
- ■
q: free text over the catch-all field (object name, file name, tags, metadata values)
- ■
bucket: restrict to a bucket
- ■
objectName: case-insensitive match on the object name only
- ■
fileName: case-insensitive match on the file name only
- ■
lastModifiedFrom, lastModifiedTo: inclusive range, ISO-8601 (2026-01-01 or 2026-01-01T00:00:00Z)
- ■
meta.<key>=<value>: exact-match filter on a custom metadata key
- ■
offset (default 0), maxResults (default 100, server cap 1000)
# Full-text search (object name, file name, tags, metadata values)
curl -u odilon:odilon "http://localhost:9234/search?q=invoice"
# Full-text restricted to a bucket
curl -u odilon:odilon "http://localhost:9234/search?bucket=documents&q=contract"
# Exact match on custom metadata key "title"
curl -u odilon:odilon "http://localhost:9234/search?meta.title=Annual%20Report%202024"
# Bucket + metadata filters
curl -u odilon:odilon "http://localhost:9234/search?bucket=photos&meta.author=alejandro&meta.year=2024"
# Free text + metadata filter
curl -u odilon:odilon "http://localhost:9234/search?q=budget&meta.department=finance"
# Pagination
curl -u odilon:odilon "http://localhost:9234/search?q=pdf&offset=100&maxResults=50"
# maxResults is capped at 1000 by the server
curl -u odilon:odilon "http://localhost:9234/search?q=*&maxResults=5000"
File name and object name queries:
# token match: tolomei-report.pdf, Tolomei_2024.docx
curl -u odilon:odilon "http://localhost:9234/search?fileName=tolomei"
# partial match anywhere, any case: atolomei.pdf, XTOLOMEIx.doc
curl -u odilon:odilon "http://localhost:9234/search?fileName=%2Atolomei%2A"
# prefix match (faster, no leading wildcard)
curl -u odilon:odilon "http://localhost:9234/search?fileName=tolomei%2A"
# exact name, case-insensitive
curl -u odilon:odilon "http://localhost:9234/search?fileName=%22tolomei-report.pdf%22"
# exact object name
curl -u odilon:odilon "http://localhost:9234/search?objectName=%22reports/2026/tolomei.pdf%22"
# single-character wildcard: ? must be encoded as %3F (matches tolomei-v1.pdf, tolomei-vX.pdf)
curl -u odilon:odilon "http://localhost:9234/search?fileName=tolomei-v%3F.pdf"
Date ranges and combined queries:
# objects modified in September 2026
curl -u odilon:odilon "http://localhost:9234/search?lastModifiedFrom=2026-09-01&lastModifiedTo=2026-09-30"
# precise timestamp
curl -u odilon:odilon "http://localhost:9234/search?lastModifiedFrom=2026-09-30T12:00:00Z"
# combined: file name + date + bucket + metadata
curl -u odilon:odilon "http://localhost:9234/search?bucket=docs&fileName=tolomei&lastModifiedFrom=2026-01-01&meta.department=legal"
Each result is a JSON object with bucketName, objectName, fileName,
size, contentType, lastModified, etag, tags and
score. The objects themselves are retrieved from Odilon storage using bucketName + objectName.
Standard queries: listObjects
List the buckets, then list the objects of a bucket. Results are paginated: offset and
pageSize select the page, and prefix restricts the list to object names starting with that prefix.
Responses are JSON.
# list buckets
curl -u odilon:odilon "http://localhost:9234/bucket/list"
# list objects of bucket "documents" (first page)
curl -u odilon:odilon "http://localhost:9234/bucket/objects/documents"
# page size and offset
curl -u odilon:odilon "http://localhost:9234/bucket/objects/documents?offset=0&pageSize=100"
# only objects whose name starts with "reports/2026/"
curl -u odilon:odilon "http://localhost:9234/bucket/objects/documents?prefix=reports/2026/&pageSize=50"
# does an object exist?
curl -u odilon:odilon "http://localhost:9234/object/exists/documents/reports/2026/tolomei.pdf"
Rebuild the search indexes
The Lucene index is secondary and can be rebuilt at any time from the object storage. A rebuild re-indexes every
object and removes orphan entries. It runs in the background: the call returns immediately.
# index status (documents, pending queue, lastIndexed, lastRebuild, state)
curl -u odilon:odilon "http://localhost:9234/search/status"
# trigger a full rebuild: 202 Accepted {"result":"rebuild started"}
# 409 Conflict {"result":"already running"} if a rebuild is in progress
curl -X POST -u odilon:odilon "http://localhost:9234/search/rebuild"
Follow the progress with /search/status (state REBUILDING while it runs). From Java use
client.searchRebuild() and client.searchStatus().