assistants

Live availability check used by the settings UI.

GET /v1/assistants/{assistant_id}/handle-available/?handle=foo

Response shape (always 200 even when unavailable — the client renders inline state, not a global error):

.. code-block:: json

{"available": true,  "code": null,        "message": null}
{"available": false, "code": "too_short", "message": "Must be at least 3 characters."}
{"available": false, "code": "taken",     "message": "This handle is already taken."}

A 429 is returned only when the per-user rate cap is exceeded — the request was not evaluated.

Authorization: the URL is scoped under /v1/assistants/{assistant_id}/ so the standard ownership filter in :class:_AssistantAPIView already enforces that the caller can see this assistant. We exclude the assistant's own current handle from the "taken" check so the UI can treat the existing value as available (useful for re-confirming without a save).

get/v1/assistants/{assistant_id}/handle-available/

Request

  • The document declares no server URL.
  • Auth: one of:
    • HTTP bearer
    • API key in cookie sessionid
    • API key in header X-Session-Token

Path parameters

assistant_idstring uuid required

Query parameters

handlestring required

Candidate handle (will be lowercased before check).

Headers

Vellum-Organization-Idstring uuid

Required if using Cookie-based or X-Session-Token authentication methods.

Response

availableboolean required
codestring nullable
messagestring nullable

Changes

No recorded changes to this operation across all 50 revisions of this API.