Admin Web API Reference

Selu provides several admin-only HTTP endpoints for managing agents, users, and system configuration. All endpoints require authentication via session cookie.

Agent Management

POST /agents/update/start

Start an agent update job in the background.

Request:

POST /agents/update/start
Content-Type: application/x-www-form-urlencoded

entry_json={"id":"weather","name":"Weather Assistant",...}

Parameters:

• entry_json (string) — JSON-encoded marketplace entry for the agent to update

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Response:

{
  "error_key": "agents.update.error.invalid_payload"
}

GET /agents/update/status/{job_id}

Get the current status of a background agent update job.

Parameters:

• job_id (path) — UUID of the update job

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "weather",
  "agent_name": "Weather Assistant",
  "target_version": "1.2.0",
  "progress": 75,
  "message_key": "agents.update.phase.downloading",
  "done": false,
  "success": false,
  "redirect_to": null,
  "error_key": null
}

Response Fields:

• progress (number) — Completion percentage (0-100)
• message_key (string) — I18n key for current status message
• done (boolean) — Whether the job has completed
• success (boolean) — Whether the job completed successfully (only meaningful if done is true)
• redirect_to (string|null) — URL to redirect to after completion (typically setup page)
• error_key (string|null) — I18n key for error message if job failed

Status Message Keys:

• agents.update.phase.preparing — Job is starting
• agents.update.phase.downloading — Downloading Docker images
• agents.update.success.updated — Update completed successfully
• agents.update.success.setup_required — Update completed, setup required
• agents.update.error.docker — Docker connection failed
• agents.update.error.start — Failed to start update
• agents.update.error.failed — Update process failed

POST /agents/update (legacy)

Synchronous agent update endpoint. Still available for form-based updates but may block for several minutes.

Request:

POST /agents/update
Content-Type: application/x-www-form-urlencoded

entry_json={"id":"weather","name":"Weather Assistant",...}

Response: HTTP 302 redirect to agents page or setup wizard.

System Updates

GET /system-updates

Display the system updates management interface (admin only).

Query Parameters:

• error_key (optional) — I18n key for error message to display
• success_key (optional) — I18n key for success message to display

Response: HTML page with current system status, including:

• Current installed version with build number
• Available version with changelog link
• Update/rollback controls
• Release channel configuration
• Auto-update settings

POST /system-updates/channel

Change the release channel.

Request:

POST /system-updates/channel
Content-Type: application/x-www-form-urlencoded

release_channel=stable

Parameters:

• release_channel (string) — Must be stable, dev, or nightly

Response: HTTP 302 redirect with success/error message

POST /system-updates/check

Manually trigger an update check.

Response: HTTP 302 redirect with results:

• Success if update available or already current
• Error if check failed

POST /system-updates/apply

Apply an available system update.

Response: HTTP 302 redirect with status:

• For sidecar mode: Job started successfully
• For in-process mode: Update completed
• Error if update failed to start

POST /system-updates/rollback

Roll back to the previous system version.

Response: HTTP 302 redirect with status:

• For sidecar mode: Rollback started
• For in-process mode: Rollback completed
• Error if rollback failed or no previous version available

GET /system-updates/job-status

Get current system update job status (for live UI updates).

Response:

{
  "active_job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "updating",
  "progress_key": "updates.progress.downloading",
  "last_error": "",
  "last_checked_at": "2026-03-17T10:30:00Z",
  "last_attempt_at": "2026-03-17T10:35:00Z",
  "installed_version": "v1.5.0",
  "installed_display": "v1.5.0 (build 123)",
  "installed_release_version": "v1.5.0",
  "installed_build_number": "123",
  "available_version": "v1.5.1-dev",
  "available_display": "v1.5.1-dev (build 124)",
  "available_release_version": "v1.5.1-dev",
  "available_build_number": "124",
  "available_changelog_url": "https://selu.bot/changelog/v1.5.1",
  "previous_version": "v1.4.9",
  "previous_display": "v1.4.9 (build 122)",
  "previous_release_version": "v1.4.9",
  "previous_build_number": "122",
  "update_available": true,
  "rollback_available": true
}

Response Fields:

• *_display (string) — Human-readable version with build number
• *_release_version (string) — Semantic version (e.g., v1.5.0-dev)
• *_build_number (string) — Build identifier for tracking
• available_changelog_url (string) — URL to changelog for available version
• update_available (boolean) — Whether an update can be applied

Note

The UpdateJobStatusResponse also includes an available_changelog_body field containing the raw changelog content for the available version. This field is not currently documented above but may appear in API responses.

• rollback_available (boolean) — Whether rollback is possible

POST /system-updates/auto-update

Toggle automatic updates on/off.

Request:

POST /system-updates/auto-update
Content-Type: application/x-www-form-urlencoded

auto_update=1

Parameters:

• auto_update (string) — 1 to enable, 0 to disable

Response: HTTP 302 redirect with confirmation message

Tool Policy Management

POST /agents/{agent_id}/policy

Update a tool policy for a specific agent. Used by the HTMX-powered permissions interface.

Parameters:

• agent_id (path) — Agent identifier
• capability_id (form) — Capability ID (use __builtin__ for built-in tools)
• tool_name (form) — Tool name
• policy (form) — Policy value: allow, ask, or block
• scope (form) — global (admin only) or user (default)

Request:

POST /agents/weather/policy
Content-Type: application/x-www-form-urlencoded

capability_id=search&tool_name=web_search&policy=ask&scope=user

Response: HTTP 200 (empty body) on success, HTTP 500 on error.

POST /agents/{agent_id}/policy/reset

Reset a user’s personal policy override back to the global default.

Parameters:

• agent_id (path) — Agent identifier
• capability_id (form) — Capability ID
• tool_name (form) — Tool name
• return_to (form, optional) — URL to redirect to after reset

Response: HTTP 200 with HX-Redirect header pointing to the agent permissions page.

Update Job Lifecycle

Agent updates follow this flow:

1. Start — POST to /agents/update/start returns a job_id
2. Poll — GET /agents/update/status/:job_id repeatedly until done: true
3. Handle Result — Check success field and redirect_to URL

System updates follow this flow:

1. Check — POST to /system-updates/check to detect available updates
2. Apply — POST to /system-updates/apply to start update process
3. Monitor — GET /system-updates/job-status to track progress
4. Complete — Update applies automatically with rollback on failure

Progress Tracking

The progress_key field in system update responses maps to I18n keys:

• updates.progress.checking — Fetching release metadata
• updates.progress.downloading — Downloading new Docker image
• updates.progress.restarting — Restarting with new version
• updates.progress.health_check — Running post-update validation
• updates.progress.apply_done — Update completed successfully

Version Display

System updates separate user-facing version display from internal Docker tags:

• Version — Semantic version like v1.5.0-dev
• Build — Specific build number for tracking
• Display — Combined format like v1.5.0-dev (build 124)
• Changelog — URL to detailed release notes

This allows clear communication about what version users are running while maintaining precise build tracking for support.

Error Handling

If an update fails:

• done will be true
• success will be false
• error_key will contain an I18n key for the error message
• Automatic rollback may occur for system updates
• Existing installation remains unchanged for agent updates

Authentication

All admin endpoints require:

1. Valid session cookie (from /login)
2. User account with is_admin = 1

Unauthorized requests return HTTP 403.

Note

Event subscription endpoints (/subscriptions) have been temporarily disabled and are not available in the current API version.

Tip

Poll the status endpoint every 1-2 seconds for responsive progress updates. The endpoint is lightweight and designed for frequent polling.

Caution

Update jobs are tied to the user who started them. Other users cannot access job status, even admins.