---
title: "Check whether a project handle is free"
method: GET
path: "/v1/project-handles/{handle}"
---

# Check whether a project handle is free

`GET /v1/project-handles/{handle}`

## Request

- Base URL: `https://app.ohmyho.st`
- URL: `https://app.ohmyho.st/v1/project-handles/{handle}`
- Auth: HTTP bearer

Reports whether a handle can be used for a project and why not when it cannot, with free alternatives an agent can offer. A handle is one to five lowercase words of letters and digits separated by single hyphens, three to fifty-nine characters, and never one of the reserved words. Availability is answered across all projects without revealing which organization holds a taken handle.

## Path parameters

- `handle` string, required

## Headers

- `X-Request-Id` string

## Response `200`

Whether the handle is usable, and alternatives when it is not.

- ProjectHandleAvailability
  - `handle` string, required: The handle exactly as it was asked about.
  - `available` boolean, required: True when a project may take this handle now.
  - `reason` 'taken' | 'too_short' | 'too_long' | 'invalid_shape' | 'prohibited_word': Why the handle cannot be used. Absent when it is available.
  - `alternatives` string[], required: Free handles to offer instead, empty when the handle is available.

## Other responses

- `400`: The request failed.
- `401`: The request failed.
- `403`: The request failed.
- `429`: The request failed.
- `503`: The request failed.

---

[API](https://skmtc.dev/ohmyho/apis/ohmyho-st-api.md) · [All operations](https://skmtc.dev/ohmyho/apis/ohmyho-st-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ohmyho/apis/ohmyho-st-api/revisions/d069888c0017?raw)