// OPENBOX DOCS

API 2.1 changes

The 2.1 contract — /api/v2-only dispatch, retired-surface 410 documents, the cursor jobs panel, and backup format 1 write retirement.

2.1 made the 2.0 contracts permanent. The public API is /api/v2 only; unversioned /api/* paths are no longer dispatched, /api/v1 is removed, and the legacy native-host names are gone. Backups write format 2 only, and the jobs panel reads the cursor-based v2 list.

v2-only dispatch

RequestResult in 2.1 and later
/api/v2/*Dispatched.
/api/host/*Dispatched to the native-window channel after the API-version guard.
/api/v1/*410 V1_API_REMOVED with detail.use pointing at /api/v2.
/api/launch, /api/shutdown, /api/native/capabilities410 HOST_CHANNEL_RETIRED with the replacement host path.
Any other /api/* path with a /api/v2 twin410 API_VERSION_REQUIRED with detail.use pointing at the v2 path.
Any other /api/* path with no v2 twin404 ROUTE_NOT_FOUND.

OPENBOX_ENABLE_V1_API is ignored with a startup warning. Retired paths authenticate before they return their 410, so an unauthenticated caller still receives 403.

Jobs panel

GET /api/v2/jobs returns a cursor list, not the old job-name map:

{
  "cursor": "",
  "next_cursor": "…",
  "jobs": [
    { "job_id": "…", "type": "metadata-sync", "state": "running", "…": "…" }
  ]
}

Query parameters: limit (default 50, max 100), cursor, type or type_filter, state or state_filter, root_job_id, and group_by=root_job_id. Per-operation rows are at GET /api/v2/jobs/items?job_id=…. POST /api/v2/jobs/cancel, /retry, and /resume return 202 with the updated job row. The legacy job-name map and GET /api/jobs are gone.

Backups

Format 2 is the only writable format. Format 1 archives still restore. A new format 1 write returns 410 BACKUP_FORMAT_RETIRED with the message "Backup format 1 is no longer written by OpenBox 2.1. Use a 2.0.x build to create a 1.19-compatible export." See Library backups.

Media manifest

media_manifest_enabled now controls record, verify, and repair. Turning it off skips manifest writes and media hashing; the integrity report says the manifest is disabled instead of reporting every file as untracked. See Configuration.

Versioned asset routes

Covers, theme CSS, theme sounds, RetroAchievements badges, documents, platform videos, startup videos, and the reader use /api/v2/*. The unversioned request path is no longer a second way in.