# Alias availability

`POST /functions/v1/alias-availability`

Handle format, reserved names, deterministic suggestions and a short reservation — with keystroke feedback that never looks like a failure.

A publishable `pk_` key is valid here. An anonymous caller — no merchant key — may call `check` only.

## Three actions

| action | What it does |
| --- | --- |
| check (default) | Is this alias free, and is the format valid |
| reserve | Hold it between choosing and finishing signup |
| release | Give it back early |

## Format, owned by the engine

```
^[a-z][a-z0-9_]{2,29}$
```

Lowercase letters, digits and underscore; must start with a letter; no trailing underscore; no double underscore; 3–30 characters. Input is normalised before validation — a leading `@` dropped, trimmed, lowercased, invalid characters stripped — and the normalised alias is echoed back, so the screen shows exactly what would be claimed.

## A bad format is not an error

It is `200` with `format_ok: false` and a named code, so keystroke feedback never looks like a failure: `ALIAS_TOO_SHORT`, `ALIAS_TOO_LONG`, `ALIAS_MUST_START_WITH_LETTER`, `ALIAS_INVALID_CHARS`, `ALIAS_TRAILING_UNDERSCORE`, `ALIAS_DOUBLE_UNDERSCORE`, `ALIAS_RESERVED`.

```
curl -X POST https://api.sidaxis.com/functions/v1/alias-availability \
  -H "x-sidaxis-api-key: pk_live_..." \
  -H "content-type: application/json" \
  -d '{ "action": "check", "alias": "@Ana_Costa" }'
```

200:

```
{
  "alias": "ana_costa",
  "format_ok": true,
  "available": false,
  "suggestions": ["ana_costa1", "ana_costa_2", "anacosta"]
}
```

## Reserved names

About 90 aliases nobody can claim: brand (`sidaxis`, `sieve`, `rostopay`, `aura`), institutional (`admin`, `support`, `security`, `legal`, `official`) and technical surfaces (`api`, `login`, `receipt`, `mandate`, `payment`). Refused with `ALIAS_RESERVED`.

## Suggestions

When an alias is taken, up to three suggestions are returned. They are deterministic — no randomness — and each is verified free before it is offered.

## Reservation

`reserve` holds the alias for `ttl_seconds`, default 300, maximum 900, and returns a `claim_token` so the surface can release it early if the person changes her mind. A reservation expires on its own — nothing has to run for the alias to come back. Losing a race is `409 ALIAS_TAKEN`.

## Limits

Per minute: `check` 120 with a merchant key, 30 anonymous per IP; `reserve` and `release` 10. Responses are `cache-control: no-store`. Debounce keystrokes around 250 ms. See [rate limits](/rate-limits).

> `user_id` is never accepted and never returned here. The identity id is minted by the engine at enrollment; an alias is only a public handle attached to it.