Skip to main content
The IPED Web API provides RESTful HTTP endpoints for searching, retrieving, and manipulating evidence items remotely.

​
Starting the Web API Server

Start the Web API server using the command line: 
java -jar iped.jar --webapi \
  --host=0.0.0.0 \
  --port=8080 \
  --sources=/path/to/sources.json

​
Command Line Options

​
--host
string
default:"0.0.0.0"
Host address to bind the server. Use 127.0.0.1 for local access only.
​
--port
int
default:"8080"
Port number for the HTTP server
​
--sources
string
required
Path to JSON file or URL containing case source definitions

​
Sources Configuration

Create a sources.json file defining available cases: 
[
  {
    "id": "case1",
    "path": "/data/iped-cases/case-2024-001"
  },
  {
    "id": "case2",
    "path": "/data/iped-cases/case-2024-002"
  }
]

​
Base URL

All endpoints are relative to: http://HOST:PORT Example: http://localhost:8080

​
Sources Endpoints

​
List Sources

Retrieve all available case sources. 
curl "http://localhost:8080/sources"
​
data
array
Array of source objects
Response Example: 
{
  "data": [
    {
      "id": "case1",
      "path": "/data/iped-cases/case-2024-001"
    },
    {
      "id": "case2",
      "path": "/data/iped-cases/case-2024-002"
    }
  ]
}

​
Get Source Details

Retrieve information about a specific source. Endpoint: GET /sources/{sourceID}
​
sourceID
string
required
Source identifier
curl "http://localhost:8080/sources/case1"
Response Example: 
{
  "id": "case1",
  "path": "/data/iped-cases/case-2024-001"
}

​
Add Source

Dynamically add a new case source. Endpoint: POST /sources
​
id
string
required
Unique identifier for the source
​
path
string
required
Filesystem path to the case directory
curl -X POST "http://localhost:8080/sources" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "case3",
    "path": "/data/iped-cases/case-2024-003"
  }'

​
Search Endpoint

​
Search Documents

Search for documents across all sources or a specific source. Endpoint: GET /search
​
q
string
required
Lucene query string (see Search API for syntax)
​
sourceID
string
Optional source identifier to search within a specific case. If omitted, searches all sources.
# Search all sources
curl "http://localhost:8080/search?q=type:pdf"

# Search specific source
curl "http://localhost:8080/search?q=type:pdf&sourceID=case1"
​
docs
array
Array of document references
Response Example: 
{
  "docs": [
    {"source": "case1", "id": 12345},
    {"source": "case1", "id": 12346},
    {"source": "case2", "id": 5678}
  ]
}

​
Query Examples

# Find PDFs
curl "http://localhost:8080/search?q=type:pdf"

# Find images
curl "http://localhost:8080/search?q=category:images"

# Complex query
curl "http://localhost:8080/search?q=type:pdf+AND+content:confidential"

# URL-encoded query
curl "http://localhost:8080/search?q=name%3Areport.pdf"

​
Document Endpoints

​
Get Document Properties

Retrieve all properties and metadata for a document. Endpoint: GET /sources/{sourceID}/docs/{id}
​
sourceID
string
required
Source identifier
​
id
int
required
Item ID
curl "http://localhost:8080/sources/case1/docs/12345"
​
source
string
Source identifier
​
id
int
Item ID
​
luceneId
int
Internal Lucene document ID
​
properties
object
Map of property names to arrays of values
​
bookmarks
array
Array of bookmark names assigned to this item
​
selected
boolean
Whether the item is selected/checked
Response Example: 
{
  "source": "case1",
  "id": 12345,
  "luceneId": 98765,
  "properties": {
    "name": ["report.pdf"],
    "path": ["/evidence/documents/report.pdf"],
    "length": ["2456789"],
    "type": ["pdf"],
    "hash": ["d41d8cd98f00b204e9800998ecf8427e"],
    "modificationDate": ["2024-01-15T10:30:00Z"],
    "category": ["documents"],
    "author": ["John Doe"],
    "title": ["Investigation Report"]
  },
  "bookmarks": ["important", "reviewed"],
  "selected": true
}

​
Get Document Content

Download the raw binary content of a document. Endpoint: GET /sources/{sourceID}/docs/{id}/content
​
sourceID
string
required
Source identifier
​
id
int
required
Item ID
# Download to file
curl "http://localhost:8080/sources/case1/docs/12345/content" \
  -o downloaded-file.pdf
Response:
  • Content-Type: application/octet-stream
  • Content-Disposition: attachment; filename="original-filename.ext"
  • Binary content stream

​
Get Document Text

Retrieve the extracted text content of a document. Endpoint: GET /sources/{sourceID}/docs/{id}/text
​
sourceID
string
required
Source identifier
​
id
int
required
Item ID
curl "http://localhost:8080/sources/case1/docs/12345/text"
Response:
  • Content-Type: text/plain; charset=UTF-8
  • Extracted text content

​
Bookmark Endpoints

​
List Bookmarks

Get all bookmark names across all sources. Endpoint: GET /bookmarks 
curl "http://localhost:8080/bookmarks"
Response Example: 
{
  "data": ["important", "reviewed", "evidence", "suspicious"]
}

​
List Bookmark Documents

Get all documents in a specific bookmark. Endpoint: GET /bookmarks/{bookmark}
​
bookmark
string
required
Bookmark name
curl "http://localhost:8080/bookmarks/important"
Response Example: 
{
  "docs": [
    {"source": "case1", "id": 12345},
    {"source": "case1", "id": 12346},
    {"source": "case2", "id": 5678}
  ]
}

​
Create Bookmark

Create a new bookmark. Endpoint: POST /bookmarks/{bookmark}
​
bookmark
string
required
Name for the new bookmark
curl -X POST "http://localhost:8080/bookmarks/new-bookmark"

​
Add Documents to Bookmark

Add documents to an existing bookmark. Endpoint: PUT /bookmarks/{bookmark}/add
​
bookmark
string
required
Bookmark name
​
docs
array
required
Array of document references to add
curl -X PUT "http://localhost:8080/bookmarks/important/add" \
  -H "Content-Type: application/json" \
  -d '[
    {"source": "case1", "id": 12345},
    {"source": "case1", "id": 12346}
  ]'

​
Remove Documents from Bookmark

Remove documents from a bookmark. Endpoint: PUT /bookmarks/{bookmark}/remove
​
bookmark
string
required
Bookmark name
​
docs
array
required
Array of document references to remove
curl -X PUT "http://localhost:8080/bookmarks/important/remove" \
  -H "Content-Type: application/json" \
  -d '[
    {"source": "case1", "id": 12345}
  ]'

​
Delete Bookmark

Delete a bookmark and all its associations. Endpoint: DELETE /bookmarks/{bookmark}
​
bookmark
string
required
Bookmark name to delete
curl -X DELETE "http://localhost:8080/bookmarks/old-bookmark"

​
Rename Bookmark

Rename an existing bookmark. Endpoint: PUT /bookmarks/{old}/rename/{new}
​
old
string
required
Current bookmark name
​
new
string
required
New bookmark name
curl -X PUT "http://localhost:8080/bookmarks/temp/rename/archived"

​
Error Responses

API endpoints return standard HTTP status codes:
Status CodeDescription
200Success
400Bad request (invalid parameters)
404Resource not found
500Internal server error
Error Response Example: 
{
  "error": "Source not found: invalid-source",
  "status": 404
}

​
Rate Limiting

The API does not currently implement built-in rate limiting. For production deployments, implement rate limiting via reverse proxy (see Authentication).

​
Swagger/OpenAPI

The API provides Swagger documentation: Endpoint: GET /application.wadl Access interactive API docs at: http://localhost:8080/application.wadl

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us