Admin API: user management, audit, search, settings

The admin endpoints provide user lifecycle management, a tamper-evident audit log with SHA-256 hash-chain verification, full-text Elasticsearch search across a world’s index, and per-user AI settings management. All /admin/* endpoints require the admin role. The /settings endpoints are available to any authenticated user and apply per-user; changes to API keys and model selections are recorded in the audit log without storing the key values.

GET /admin/users

GET /admin/users List all users in the system. Admin only.

Response

users

object[]

Array of user records.

Show user fields

uid

string

Unique user identifier (slug format: alphanumeric + ._-, starts with alphanumeric, max 64 chars).

string | null

Email address, or null if not set.

display_name

string | null

Human-readable display name.

role

string

"user" or "admin".

status

string

"active", "disabled", or "pending".

created_at

string

ISO 8601 timestamp when the account was created.

ISO 8601 timestamp of the most recent successful login, or null.

curl -s http://localhost:8000/admin/users \
  -b "sherpa_session=<token>"

POST /admin/users

POST /admin/users Create a new user. The user is created with status: "active" immediately. A personal workspace directory is provisioned on creation. Admin only.

Request body

uid

string

required

Unique identifier for the new user. Must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$. Cannot be changed after creation.

display_name

string

Human-readable name shown in the UI.

role

string

default:"user"

Initial role: "user" or "admin".

password

string

required

Initial plaintext password. Stored as a bcrypt hash; the plaintext is never persisted.

string

Email address. Optional.

Response

boolean

true on success.

user

object

The created user record (same fields as GET /admin/users items, without password_hash).

curl -s -X POST http://localhost:8000/admin/users \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{
    "uid": "alice",
    "display_name": "Alice",
    "role": "user",
    "password": "initial-secret-123",
    "email": "alice@example.com"
  }'

PATCH /admin/users/

PATCH /admin/users/{uid} Update a user’s status, role, password, or display name. All fields are optional; at least one must be provided. Admins cannot disable their own account. Admin only.

Path parameters

uid

string

required

The uid of the user to update.

Request body

status

string

New account status: "active" or "disabled". Setting "disabled" prevents login. An admin cannot disable their own account.

role

string

New role: "user" or "admin".

password

string

New plaintext password. Stored as a bcrypt hash.

display_name

string

New display name.

Response

boolean

true on success.

uid

string

The uid of the updated user.

curl -s -X PATCH http://localhost:8000/admin/users/alice \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{"status": "disabled"}'

GET /admin/audit

GET /admin/audit Query the audit log. All filter parameters are optional and combined with AND semantics. Viewing the audit log is itself recorded as an admin.audit_viewed event (fail-closed — the view is blocked if the audit write fails). Admin only.

Query parameters

actor

string

Filter by the uid of the user who performed the action.

action

string

Filter by action name (e.g. auth.login, user.created, document.downloaded, world.deleted).

resource_type

string

Filter by the type of resource affected (e.g. user, world, document, workspace_file, audit_log, share, settings).

resource_id

string

Filter by a specific resource identifier (e.g. world:payroll-2024, user:alice).

outcome

string

Filter by outcome: success, failure, deny, or error.

severity

string

Filter by severity level: info, warning, critical.

time_from

string

ISO 8601 start of the time range (inclusive).

time_to

string

ISO 8601 end of the time range (inclusive).

request_id

string

Filter by a specific request correlation ID.

limit

integer

default:"100"

Maximum number of rows to return. Range: 1–500.

offset

integer

default:"0"

Pagination offset.

Response

rows

object[]

Matching audit log entries.

Show audit log row fields

integer

Row ID (sequential, used for hash-chain ordering).

actor

string | null

uid of the acting user, or null for system events.

action

string

Action name (dot-separated, e.g. auth.login).

resource_type

string

Type of the affected resource.

resource_id

string | null

Specific resource identifier.

outcome

string

"success", "failure", "deny", or "error".

reason

string | null

Machine-readable failure reason when outcome is not "success".

severity

string

"info", "warning", or "critical".

ip_hash

string | null

HMAC-SHA256 hash of the client IP (raw IP is never stored).

user_agent

string | null

Client User-Agent string (truncated to 512 chars).

before_state

object | null

Snapshot of relevant fields before the change, for mutating operations.

after_state

object | null

Snapshot of relevant fields after the change.

detail

object | null

Structured additional context for the event.

created_at

string

ISO 8601 timestamp.

entry_hash

string | null

SHA-256 hash-chain digest for this row. null for legacy rows predating hash-chain activation.

count

integer

Number of rows in this response page.

offset

integer

The pagination offset that was applied.

limit

integer

The limit that was applied.

curl -s "http://localhost:8000/admin/audit?\
action=auth.login&\
time_from=2024-01-01T00:00:00Z&\
limit=50" \
  -b "sherpa_session=<token>"

GET /admin/audit/verify

GET /admin/audit/verify Verify the SHA-256 hash-chain integrity of the audit log. This detects tampering, row deletion, row insertion, reordering, and truncation of the chain-protected portion of the log. The verification itself is recorded as an admin.audit_verified event (fail-closed). Admin only.

Response

boolean

true if the hash chain is intact; false if any integrity violation was detected.

checked

integer

Number of hash-chained rows that were verified.

broken_at

integer | null

Row id where the first integrity violation was detected, or null when ok is true.

reason

string | null

Machine-readable reason for the failure. Values include prev_hash_mismatch, entry_hash_mismatch, missing_head, count_mismatch. null when ok is true.

curl -s http://localhost:8000/admin/audit/verify \
  -b "sherpa_session=<token>"

GET /admin/es/search

GET /admin/es/search Full-text BM25 search against a world’s Elasticsearch index. Returns document chunks with their doc_id, a text excerpt, and a relevance score. Admin only.

Query parameters

version

string

default:"v1"

required

World identifier.

query

string

required

Search query string. Minimum length 1 character.

scope_paths

string[]

Repeated parameter. Restrict results to documents within these subfolder prefixes.

integer

default:"20"

Maximum number of hits to return. Range: 1–50.

Response

version

string

World ID the search was executed against.

query

string

The query string that was executed.

scope_paths

string[]

The normalised scope prefix list used, or an empty array for an unscoped search.

hits

object[]

Search result chunks, sorted by relevance score descending.

Show hit fields

doc_id

string

World-root-relative path of the source document.

line

integer | null

Approximate line number of the matching chunk.

snippet

string

Text excerpt of the matching chunk.

score

number

BM25 relevance score.

ext

string | null

File extension of the source document.

curl -s "http://localhost:8000/admin/es/search?\
version=payroll-2024&\
query=income+tax+calculation&\
k=10" \
  -b "sherpa_session=<token>"

GET /settings

GET /settings Retrieve the current AI settings for the authenticated user. API key values are never returned; instead, openai_key_set and gemini_key_set boolean flags indicate whether a key has been stored.

Response

agent

string

Active agent backend: "heuristic", "openai", "gemini", "ollama", or "codex".

codex_reasoning

string | null

Codex reasoning effort level ("low", "medium", "high").

codex_model

string | null

Codex model name.

openai_model

string | null

OpenAI model name.

openai_key_set

boolean

true if an OpenAI API key has been stored for this user.

ollama_url

string | null

Ollama server URL.

ollama_model

string | null

Ollama model name.

gemini_key_set

boolean

true if a Gemini API key has been stored for this user.

gemini_model

string | null

Gemini model name.

extract_provider

string

Provider used for knowledge extraction: "auto", "openai", "gemini", or "ollama".

system_prompt

string

Custom system prompt, or an empty string if not set.

curl -s http://localhost:8000/settings \
  -b "sherpa_session=<token>"

PUT /settings

PUT /settings Update AI settings for the authenticated user. All fields are optional; only provided (non-null) fields are updated. API key changes are audited as <set> or <cleared> (the key value itself is never written to the audit log). Returns the same shape as GET /settings.

Request body

agent

string

Agent backend to activate: "heuristic", "openai", "gemini", "ollama", or "codex".

codex_reasoning

string

Codex reasoning effort: "low", "medium", or "high".

codex_model

string

Codex model name (e.g. "gpt-5.5").

openai_api_key

string

OpenAI API key. Stored encrypted; never returned in responses.

openai_model

string

OpenAI model name (e.g. "gpt-4o").

ollama_url

string

Ollama server URL (e.g. "http://localhost:11434").

ollama_model

string

Ollama model name (e.g. "qwen2.5").

gemini_api_key

string

Google Gemini API key. Stored encrypted; never returned in responses.

gemini_model

string

Gemini model name (e.g. "gemini-2.5-flash").

extract_provider

string

Provider for knowledge graph extraction: "auto", "openai", "gemini", or "ollama".

system_prompt

string

Custom system prompt prepended to every chat request for this user.

curl -s -X PUT http://localhost:8000/settings \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{
    "agent": "openai",
    "openai_api_key": "sk-...",
    "openai_model": "gpt-4o"
  }'

POST /settings/test

POST /settings/test Test connectivity to an AI provider without saving any settings. Sends a minimal probe request to the specified provider and returns the result. Useful for validating API keys and model names before committing them with PUT /settings.

Request body

provider

string

required

Provider to test: "openai", "gemini", "ollama", or "codex".

openai_api_key

string

API key to test. If omitted, falls back to the user’s stored key.

openai_model

string

Model to test. Falls back to the user’s stored model.

gemini_api_key

string

Gemini API key to test.

gemini_model

string

Gemini model to test.

ollama_url

string

Ollama URL to test.

ollama_model

string

Ollama model to test.

codex_model

string

Codex model to test.

Response

boolean

true if the provider responded successfully.

provider

string

Provider that was tested.

model

string

Model that was used in the probe.

detail

string

Human-readable result message. On success: "接続OK". On failure: the error description (e.g. "401 Unauthorized", "model not found", "codex CLI が見つかりません").

curl -s -X POST http://localhost:8000/settings/test \
  -H "Content-Type: application/json" \
  -b "sherpa_session=<token>" \
  -d '{
    "provider": "openai",
    "openai_api_key": "sk-...",
    "openai_model": "gpt-4o"
  }'

Overview

Endpoints

Admin API: user management, audit, search, settings

GET /admin/users

Response

POST /admin/users

Request body

Response

PATCH /admin/users/

Path parameters

Request body

Response

GET /admin/audit

Query parameters

Response

GET /admin/audit/verify

Response

GET /admin/es/search

Query parameters

Response

GET /settings

Response

PUT /settings

Request body

POST /settings/test

Request body

Response

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /admin/users

​Response

​POST /admin/users

​Request body

​Response

​PATCH /admin/users/

​Path parameters

​Request body

​Response

​GET /admin/audit

​Query parameters

​Response

​GET /admin/audit/verify

​Response

​GET /admin/es/search

​Query parameters

​Response

​GET /settings

​Response

​PUT /settings

​Request body

​POST /settings/test

​Request body

​Response

Build docs developers (and LLMs) love

GET /admin/users

Response

POST /admin/users

Request body

Response

PATCH /admin/users/

Path parameters

Request body

Response

GET /admin/audit

Query parameters

Response

GET /admin/audit/verify

Response

GET /admin/es/search

Query parameters

Response

GET /settings

Response

PUT /settings

Request body

POST /settings/test

Request body

Response