Web API Endpoints

Complete REST API reference for remote IPED case access

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

curl "http://localhost:8080/sources"

data · array

Array of source objects

Show Source Object

id · string

Unique source identifier

path · string

Filesystem path to the case directory

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

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

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.

cURL

# 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

Show Document Reference

source · string

Source identifier containing the document

id · int

Item ID within the source

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

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

cURL

# 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

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

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

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

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

Show Document Reference

source · string · required

Source identifier

id · int · required

Item ID

cURL

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

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

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

curl -X PUT "http://localhost:8080/bookmarks/temp/rename/archived"

Error Responses

API endpoints return standard HTTP status codes:

Status Code	Description
200	Success
400	Bad request (invalid parameters)
404	Resource not found
500	Internal 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

• Web API Authentication - Security and authentication
• Web API Examples - Complete integration examples
• Search API - Query syntax reference