Resolve or check an alias

Check availability and find the permanent card behind a claimed alias.

GET/v1/aliases/{kind}/{alias}

Access: Public; API key optional
Client: Browser fetch supported

Parameters#

Name	Location	Meaning
`kind`Required	Path	u for people, o for organisations.
`alias`Required	Path	3 to 32 ASCII letters, digits, hyphens or underscores. Starts with a letter and ends with a letter or digit.

Request examples#

cURL

curl -fsS 'https://veil.rip/v1/aliases/o/veil'

javascript

const response = await fetch("https://veil.rip/v1/aliases/o/veil");
const result = await response.json();

Try the request#

Response#

HTTP 200application/json

available and status describe the alias. Claimed aliases include identity. quarantineDays and reusableAt describe a released name. reservedFor may identify a reserved organisation.

Field	Type	Meaning
`kind`	`string`	u for a person, o for an organisation.
`alias`	`string`	Normalised alias.
`available`	`boolean`	Whether a new claim can proceed now.
`status`	`string`	available, claimed, reserved_name, publishing or quarantined.
`url`	`string`	Alias address being checked.
`identity`	`object \| null`	Current holder’s n and permanent url.
`reusableAt`	`string \| null`	Quarantine end time.
`quarantineDays`	`integer`	Quarantine duration, currently 30 days.
`previousIdentity`	`object \| null`	Previous holder when disclosed for quarantine.
`reservedFor`	`object \| null`	Card allowed to reclaim a reserved alias, when applicable.

Example response

Illustrative values. Read the current response from your request.

json

{
  "kind": "u",
  "alias": "sample-person",
  "available": true,
  "status": "available",
  "url": "https://veil.rip/u/sample-person",
  "identity": null,
  "reusableAt": null,
  "quarantineDays": 30,
  "previousIdentity": null,
  "reservedFor": null
}

Response headers#

Header	Value	Meaning
`Content-Type`	`application/json`	Use the declared media type before choosing a parser.
`Date`	`HTTP date`	Server time. Compare it with your clock when signing requests.
`Retry-After`	`integer seconds, on rate_limited or busy`	Wait at least this long before retrying. Other 429/503 codes do not necessarily include it.

Usage notes#

Availability does not reserve a name. Claiming an alias uses a signed version. Store the permanent number because names can be released and reassigned.

Errors#

API errors return an error object. Use error.code for program logic; error.message is English text for people and can change. Response and error guide

HTTP Code Meaning and next step

400

HTTP	Code	Meaning and next step
400	`invalid_alias`	The alias does not meet the ASCII name rules. Use 3 to 32 lowercase ASCII letters, digits, hyphens or underscores; start with a letter and end with a letter or digit.
400	`invalid_parameter`	A path, query or body field is missing, malformed or outside its accepted range. Correct the field named in `error.message` before sending again.

invalid_alias

The alias does not meet the ASCII name rules.

Use 3 to 32 lowercase ASCII letters, digits, hyphens or underscores; start with a letter and end with a letter or digit.

400

invalid_parameter

A path, query or body field is missing, malformed or outside its accepted range.

Correct the field named in error.message before sending again.

When using an optional API key

HTTP	Code	Meaning and next step
401	`invalid_api_key`	The bearer credential is malformed, unknown, expired or revoked. Use an active key. To use anonymous public access, remove `Authorization` entirely. Invalid credentials never fall back automatically.
403	`api_key_scope`	The API key lacks read or verify scope, or the endpoint does not accept bearer keys. Use the correct scope. Identity writes and key management still require a device signature.
403	`api_key_suspended`	This API key is suspended. Ask staff to restore it; another key cannot lift an account suspension.
403	`developer_suspended`	The owner’s API account is suspended or the owner card is unavailable. Check the owner account and any staff restriction. Creating another key does not bypass suspension.

Shared request errors

HTTP Code Meaning and next step

429

HTTP	Code	Meaning and next step
429	`rate_limited`	An anonymous, signed-request or API-key allowance was exceeded. Wait at least `Retry-After` seconds. Share a queue and retry budget across your workers.
500	`internal_error`	An unexpected server error occurred. Internal details are not returned. Retry reads with bounded backoff. Check write results before sending a new signed operation.
503	`busy`	The application has reached a temporary concurrency or database limit. Wait `Retry-After` seconds and retry with bounded backoff.

rate_limited

An anonymous, signed-request or API-key allowance was exceeded.

Wait at least Retry-After seconds. Share a queue and retry budget across your workers.

500

internal_error

An unexpected server error occurred. Internal details are not returned.

Retry reads with bounded backoff. Check write results before sending a new signed operation.

503

busy

The application has reached a temporary concurrency or database limit.

Wait Retry-After seconds and retry with bounded backoff.

Read this entry as JSON