Check Username Availability
Reports whether a username can be claimed. Intended to drive live feedback in a username picker before `PUT /users/me/username` is called. This route carries **no API-key scope gate**, unlike the rest of the Users module — but it is still not anonymous, so it needs an API key or a whitelisted first-party origin. The path segment is normalised the same way the update endpoint normalises it, and `normalizedUsername` echoes back the value that would actually be stored. A `200` with `available: false` is the normal negative answer — an unavailable name is not an error.
Your personal API key — vw_ followed by 64 hex characters. The same key is also accepted
as Authorization: Bearer vw_....
In: header
Path Parameters
The candidate username. Normalised server-side before the lookup.
Response Body
application/json
application/json
curl -X GET "https://example.com/api/v1/users/string/availability"{ "success": true, "message": "Username availability fetched successfully", "data": { "available": true, "normalizedUsername": "veriworkly-user" }}Set UsernamePUT
Claims the authenticated user's username. Requires the `user:write` scope when called with an API key. The username is the public identifier in share-link URLs (`/share/{username}/{slug}`) and, for accounts holding `custom_subdomain`, the published-portfolio subdomain — so a user cannot create a share link until one is set. **A username can only be set once.** Once the account has one, this endpoint rejects any different value with `409 Username is locked and cannot be changed`. Re-sending the value the account already holds is a no-op and returns `200`, so the call is safe to retry. The submitted value is **normalised before validation**: lowercased, non-`[a-z0-9_-]` characters folded to hyphens, leading/trailing hyphens stripped, and truncated to 32 characters. `Jane.Doe` and `jane-doe` therefore claim the same username. It must survive normalisation as 3–32 characters and must not be a reserved word (`admin`, `api`, `app`, `docs`, and similar platform-owned names). Check with `GET /users/{username}/availability` before committing. A successful claim invalidates the caller's cached session so the new username is visible immediately rather than at the end of the session-cache TTL.
Update Auto-Sync PreferencePUT
Turns the account-level background document sync on or off. Requires the `user:write` scope when called with an API key. This is the account-wide switch. It does not override a document's own `keepLocalOnly` flag — a document opted out individually stays local even with auto-sync on. Turning auto-sync off does not delete anything already synced; it only stops new local edits from being pushed. Defaults to `true` on a new account. A successful change invalidates the caller's cached session.