--- title: "Check a handle" method: GET path: "/account/organization-handle/availability" tags: ["account"] --- # Check a handle `GET /account/organization-handle/availability` ## Request - Base URL: `https://api.sparkvault.com/v1` - URL: `https://api.sparkvault.com/v1/account/organization-handle/availability` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Whether the organization could claim `handle` as its organization handle now. A handle any organization ever claimed is taken, this organization's own current and former handles included, given up or not: a handle is never released. A handle outside the grammar is `invalid`. A platform word, an auth.sv portal section, the first path segment of one of the API's own root routes (such as `health`), and any handle that reads as SparkVault's brand (SparkVault, SparkLink) in any spelling, such as `spark-vault` or `sparkvau1t`, is `reserved`: a handle names the host the organization's mail goes out from ({handle}.help.sv, {handle}.send.sv), so one reading as SparkVault would present that mail as SparkVault's own. Neither reads the claims. Every lookup of the claims spends the account's hourly budget of 60 handle checks, shared with claims. Org admins only, from an interactive session. ## Query parameters - `handle` string, required: An organization handle: three to 40 lowercase letters, digits and single hyphens, starting with a letter and ending with a letter or digit. ## Response `200` Whether the handle is available. - object - `data` OrganizationHandleAvailability, required: Whether the organization could claim a handle now. - `handle` string, required: The handle asked about, as sent. - `available` boolean, required - `reason` 'taken' | 'reserved' | 'invalid' | 'null', nullable, required: Why the handle cannot be claimed; null when it is available. - `meta` ResponseMeta: Envelope metadata present on every successful response. - `api_version` string - `request_id` string - `response_ms` integer - `timestamp` integer: Unix seconds. - `pools` object: Storage and bandwidth capacity snapshot for the account. - `billing` object - `past_due` boolean - `quota` object: This minute of the account request budget. Present on authenticated success responses that passed the throttle; absent otherwise. - `limit` integer - `used` integer - `remaining` integer - `resets_at` integer: Unix seconds. ## Other responses - `400`: VALIDATION_ERROR — `handle` is missing, or longer than 63 characters. - `401`: AUTHENTICATION_ERROR — missing or invalid credentials. - `403`: FORBIDDEN — the caller is not an org admin, or the credential is an API key. - `429`: RATE_LIMIT_EXCEEDED — the account has spent its 60 handle checks this hour. `Retry-After` carries the seconds until the budget reopens, and `details` carries `limit`, `used` and `resets_at`. ## Changes - **2026-10-28** `a9a10e328ba5`: 16 info - the response property `error/details` became required for the status `400` - the response property `error/details` became required for the status `401` - the response property `error/details` became required for the status `403` - the response property `error/details` became required for the status `429` - …12 more - **2026-10-28** `56d7c265a77a`: 4 breaking - the response property `error/details` became nullable for the status `400` - the response property `error/details` became nullable for the status `401` - the response property `error/details` became nullable for the status `403` - the response property `error/details` became nullable for the status `429` - **2026-10-21** `9f5e902abd83`: 1 info - endpoint added [Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/account/organization-handle/availability/get.md) --- [API](https://skmtc.dev/sparkvault/apis/sparkvault-api.md) - [All operations](https://skmtc.dev/sparkvault/apis/sparkvault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sparkvault/apis/sparkvault-api/revisions/97cfadccd0c0?raw)