API automation

Returns {"queue": [...]}. Each entry: game_id, added_at, note (max 200 characters), skip, plus resolved fields name, platform, cover, path_exists, and missing (true when the game was deleted). The persisted queue is capped at 500 entries.

Actions:

Response: {"queue": [...], "next": <entry or null>}.

{"tags": [{"tag": "...", "count": <n>}, ...]} sorted by count descending then tag; hidden games are excluded.

{"ids": [...], "tags"|"tags_add"|"tags_remove": [...]}. At least one tag change key is required. Normalization: each tag is trimmed, whitespace-collapsed, deduplicated case-insensitively, limited to 64 characters, and at most 50 tags per game; overlong tags raise 400. Returns {"updated": <count>, "tags": [...]}.

{"notifications": [...], "unread": <count>}. Notifications are newest first, capped at 200. Each item: id (nt-<hex>), kind, level, title (max 200 chars), body (max 2000 chars), created_at, read, and optional source, correlation_id, dedupe_key. Same-kind+same-title items within 600 seconds, or items with the same dedupe_key, collapse into the existing entry.

• {"action":"read", "ids": [...]} mark read (no ids marks all).
• {"action":"clear", "ids": [...]} remove (no ids clears all).
• {"action":"list"} returns the current feed.

Response: {"notifications": [...], "unread": <count>}.

{"webhooks": [...], "events": [...], "attempts": <default>, "timeout": <default>}. Webhook configs are redacted: the secret value is replaced by secret_set: true, and delivery status fields (last_status, last_error, last_sent_at, last_delivery_at) are included. events lists the nine subscribable types: session.started, session.stopped, queue.advanced, library.imported, library.changed, metadata.synced, backup.created, update.installed, plugin.changed.

Save the full webhook list plus global defaults:

{
  "webhooks": [
    {
      "id": "wh-...",
      "url": "https://example.com/hook",
      "events": ["session.started", "session.stopped"],
      "enabled": true,
      "attempts": 3,
      "timeout": 5,
      "secret": "replace-me-with-8-plus-chars"
    }
  ],
  "attempts": 3,
  "timeout": 5
}

Validation (validate_webhook):

• At most 32 configs (MAX_WEBHOOKS); a longer list raises 400.
• events must be a non-empty list of known types.
• URL must be http/https, at most 2048 characters, no embedded credentials, no fragment, valid port (1..65535).
• HTTPS is required unless OPENBOX_ALLOW_HTTP_WEBHOOKS=1 is set.
• Host must resolve to a non-reserved address: unspecified, multicast, link-local, and reserved addresses are rejected. Loopback targets must not be the running OpenBox server port (checked both by port match and by a live TCP probe).
• attempts and timeout must be numeric; effective values clamp to 1..5 and 1..15 on delivery.
• Secrets must be at least 8 characters when supplied (delivery signs only when a secret exists). A config with secret_set: true and no secret preserves the stored value.

Returns {"webhooks": [...redacted...], "events": [...]}.

{"webhook": {...}} or the config fields directly. Performs one bounded synchronous delivery of a test.ping envelope and returns {"ok": bool, "status": int|null, "error": str} without exposing the response body, resolved addresses, or credentials. The outbound request respects the config's timeout (1..15 s).

{"items": [{"id", "label"}, ...]}: Big Box, Settings, Search, then up to 40 games with ids launch:<index>. Used by the rofi/wofi/dmenu keyboard launcher.

{"exclusions": [...]}. Entries: {"source": "steam"|"heroic"|"lutris"|"gameyfin", "external_id": "..."}, optionally {"heroic": ["heroic", "<source>", "<id>"]} for store-specific Heroic exclusions.

{"source", "external_id", "heroic_source": ""} adds an exclusion (deduplicated). Returns {"exclusion": {...}}.

{"source", "external_id"} removes it. Returns {"removed": true}.

Excluded storefront entries are filtered out of future imports and storefront rescans.