Admin API Overview

Overview

Fess Admin API is a RESTful API for programmatic access to administrative functions. You can perform most operations available in the admin console via API, including crawl configuration, user management, and scheduler control.

Using this API, you can automate Fess configuration and integrate with external systems.

Base URL

The Admin API base URL follows this format:

http://<Server Name>/api/admin/

For example, in a local environment:

http://localhost:8080/api/admin/

Authentication

Access to the Admin API requires authentication using an access token.

Obtaining an Access Token

  1. Log in to the admin console

  2. Navigate to “System” -> “Access Token”

  3. Click “Create New”

  4. Enter a token name and select required permissions

  5. Click “Create” to obtain the token

Using the Token

Include the access token in the request header:

Authorization: Bearer <access_token>

Or specify it as a query parameter:

?token=<access_token>

cURL Example

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "http://localhost:8080/api/admin/scheduler/settings"

Required Permissions

To use the Admin API, the token requires the following permissions:

  • admin-* - Access to all administrative functions

  • admin-scheduler - Scheduler management only

  • admin-user - User management only

  • Other function-specific permissions

Common Patterns

List Retrieval (GET/PUT /settings)

Retrieves a list of settings.

Request

GET /api/admin/<resource>/settings
PUT /api/admin/<resource>/settings

Parameters (pagination):

Parameter Type Description
size Integer Number of items per page (default: 20)
page Integer Page number (starts from 0)

Response

{
  "response": {
    "status": 0,
    "settings": [...],
    "total": 100
  }
}

Single Setting Retrieval (GET /setting/{id})

Retrieves a single setting by ID.

Request

GET /api/admin/<resource>/setting/{id}

Response

{
  "response": {
    "status": 0,
    "setting": {...}
  }
}

Create New (POST /setting)

Creates a new setting.

Request

POST /api/admin/<resource>/setting
Content-Type: application/json

{
  "name": "...",
  "...": "..."
}

Response

{
  "response": {
    "status": 0,
    "id": "created_id",
    "created": true
  }
}

Update (PUT /setting)

Updates an existing setting.

Request

PUT /api/admin/<resource>/setting
Content-Type: application/json

{
  "id": "...",
  "name": "...",
  "...": "..."
}

Response

{
  "response": {
    "status": 0,
    "id": "updated_id",
    "created": false
  }
}

Delete (DELETE /setting/{id})

Deletes a setting.

Request

DELETE /api/admin/<resource>/setting/{id}

Response

{
  "response": {
    "status": 0,
    "id": "deleted_id",
    "created": false
  }
}

Response Format

Success Response

{
  "response": {
    "status": 0,
    ...
  }
}

status: 0 indicates success.

Error Response

{
  "response": {
    "status": 1,
    "errors": [
      {"code": "errors.failed_to_create", "args": ["...", "..."]}
    ]
  }
}

HTTP Status Codes

Code Description
200 Request successful
400 Invalid request parameters
401 Authentication required (token missing or invalid)
403 Access denied
404 Resource not found
500 Internal server error

Available APIs

Fess provides the following Admin APIs.

Crawl Configuration

Endpoint Description
WebConfig API Web crawl configuration
FileConfig API File crawl configuration
DataConfig API Data store configuration

Index Management

Endpoint Description
Documents API Document bulk operations
CrawlingInfo API Crawl information
FailureUrl API Failure URL management
Backup API Backup/Restore

Scheduler

Endpoint Description
Scheduler API Job scheduling
JobLog API Job log retrieval

User & Permission Management

Endpoint Description
User API User management
Role API Role management
Group API Group management
AccessToken API API token management

Search Tuning

Endpoint Description
LabelType API Label types
KeyMatch API Key match
BoostDoc API Document boost
ElevateWord API Elevate word
BadWord API Bad word (excluded suggestions)
RelatedContent API Related content
RelatedQuery API Related query
Suggest API Suggest management

System

Endpoint Description
General API General settings
SystemInfo API System information
Stats API System statistics
Log API Log retrieval
Storage API Storage management
Plugin API Plugin management

Dictionary

Endpoint Description
Dict API Dictionary management (synonyms, stop words, etc.)

Usage Examples

Create Web Crawl Configuration

curl -X POST "http://localhost:8080/api/admin/webconfig/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Example Site",
       "urls": "https://example.com/",
       "includedUrls": ".*example.com.*",
       "excludedUrls": "",
       "maxAccessCount": 1000,
       "depth": 3,
       "available": true
     }'

Start a Scheduled Job

curl -X PUT "http://localhost:8080/api/admin/scheduler/{job_id}/start" \
     -H "Authorization: Bearer YOUR_TOKEN"

List Users

curl "http://localhost:8080/api/admin/user/settings?size=50&page=0" \
     -H "Authorization: Bearer YOUR_TOKEN"

Reference