Check whether a signup username is free, taken, or GitHub-claimable

GET/api/auth/handle-availability

checkHandleAvailability

Powers the inline hint under the signup username field. `claimable_on_github` means the handle is owned on GitHub and (to prevent impersonation of established accounts) can only be registered through the OAuth claim-by-proof flow. Probe failures degrade to `available` — the signup POST is the authoritative, fail-closed gate.

Authentication is not described for this operation in the spec — that does not mean it is public. Check tokens and scopes.

curl

curl -X GET 'https://neosource.dev/api/auth/handle-availability?handle=HANDLE'

fetch

fetch("https://neosource.dev/api/auth/handle-availability?handle=HANDLE", {
  method: "GET",
});

Query parameters

handlerequired: Candidate username to check before signup.
string

Responses

200Availability verdict

application/json

HandleAvailabilityResponse

Inline pre-submit verdict for a signup username. `Available` means a local password account can be created; `Taken` means a neosource account already owns it; `ClaimableOnGithub` means the handle is owned on GitHub and can only be registered via the claim-by-proof flow.

one of

object
statusrequired
string
"available"
object
statusrequired
string
"taken"
object
providerrequired
string
Provider slug to drive the claim flow (currently always `github`).
provider_loginrequired
string
Case-canonical login GitHub reports for the handle.
statusrequired
string
"claimable_on_github"

Standard errors

Bodies documented once for the whole API — see standard errors.

400Invalid request body
401Invalid credentials
429Rate limited — retry after the interval in the `Retry-After` header
500Internal server error
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget