Selectors

Selectors identify which device and which session an HTTP request or WebSocket command targets.

Device selector — URL path

Used in all device-level HTTP routes as /{device_type}/{id_or_index}/….

Route example	Selector meaning
inverse3/0	First Inverse3 by index (0-based)
inverse3/A14	Inverse3 with device ID A14
inverse3/*	All Inverse3 devices (wildcard)
*inverse/*	All Inverse-family devices (Inverse3, Inverse3x, Minverse)
verse_grip/0	First wired VerseGrip by index
wireless_verse_grip/*	All Wireless VerseGrips
*verse_grip/*	All VerseGrip-family devices (wired, wireless, custom)

Rules:

• GET rejects wildcard selectors (ambiguous) → 400
• POST and DELETE accept wildcards — operation applied to all matches

Supported {device_type} values: inverse3, verse_grip, wireless_verse_grip, or family wildcards *inverse, *verse_grip.

Session selector — ?session=<expr> query parameter

Session-scoped HTTP endpoints (basis, mount, preset, filters, navigation, SDF) require a ?session=<expr> query parameter to identify which session's context to operate in.

Expression	Meaning
(omitted)	All sessions (allowed on DELETE only)
#123 or 123	Session with numeric ID 123
:0	First session by index
:-1	Last session by index
profile_name	First session with this profile (may be ambiguous)
profile_name:0	First session with profile + index 0
:default:0	First session with profile default at index 0
co.haply.hub::*:0	First session whose profile starts with co.haply.hub:: (glob wildcard)
:co.haply.hub::*:-1	Last session in the co.haply.hub:: namespace

Example:

GET /inverse3/0/config/navigation?session=:default:0

Profile-name wildcards

Profile patterns accept two glob metacharacters:

Metacharacter	Meaning
*	matches any sequence of characters (including empty)
?	matches exactly one character

Every other character — including :, ., -, [, ] — is matched literally (character classes like [abc] are not supported). Matching is case-sensitive.

A bare * (or all) keeps its existing meaning of all sessions. To match profiles whose name starts with *, include at least one other character (e.g. *foo).

Useful patterns:

• co.haply.hub::* — any profile in the co.haply.hub:: namespace
• *-update — any profile ending in -update
• co.haply.*:* — any profile whose namespace starts with co.haply.
• defaul? — any 7-character profile starting with defaul

A wildcard pattern is ambiguous on its own (it can match more than one session). To use it on a GET / POST endpoint, disambiguate with a trailing :<index>:

# First session in the Haply Hub namespace
GET /inverse3/0/config/basis?session=co.haply.hub::*:0

# Last session in a Unity namespace
GET /inverse3/0/config/mount?session=:co.haply.unity::*:-1

Ambiguous wildcards (no index) are rejected with 400 on GET/POST. They are tolerated on routes that explicitly accept multi-session matches — GET /sessions/<sel> (returns every match) and DELETE endpoints (applied to every match).

Session selector — URL path

The /sessions/{selector} endpoint accepts the same expression as a path parameter — useful for looking up a single session or verifying that one exists:

GET /sessions                      # list all active sessions
GET /sessions/:default:0           # one session by profile + index
GET /sessions/:-1                  # last active session
GET /sessions/#42                  # session id 42
GET /sessions/co.haply.hub::*      # every session in the co.haply.hub:: namespace
GET /sessions/co.haply.hub::*:0    # first session in that namespace

This is functionally equivalent to GET /sessions?session=<selector>; both routes call the same handler. GET /sessions/<sel> is one of the few endpoints that tolerates an ambiguous wildcard pattern without a :<index> suffix — it returns every match in the same list envelope as GET /sessions.

Pass selectors verbatim

Every selector form above — including #42 and profile patterns with * — is transmitted as-is by standard HTTP clients (Python requests, libhv, curl, fetch). No client-side URL encoding is needed. In shells, quote tokens that contain # or * (e.g. --session "#42", --session "co.haply.hub::*:0") to stop the shell from treating them as comments or glob-expanding them against local files.

One exception: the ? glob metacharacter is the URL query delimiter in paths. In a path-form selector (e.g. /sessions/defaul?:0) it must be percent-encoded as %3F — GET /sessions/defaul%3F:0. In a query-form selector (?session=defaul?:0), only the first ? splits the query and subsequent ? characters are passed through unchanged.

WebSocket sessions don't need selectors

On a WebSocket connection, you are the session — your configure and commands entries automatically target the current session's devices. Session selectors are only needed for HTTP requests (including cross-session remote control — see Sessions).