---
title: "Declare Name"
method: POST
path: "/v1/users/{end_user}/names"
tags: ["v1"]
---

# Declare Name

`POST /v1/users/{end_user}/names`

## Request

- Base URL: `https://api.korely.ai`
- URL: `https://api.korely.ai/v1/users/{end_user}/names`
- Auth: HTTP bearer

Declare that this end user is also called `name`.

The store never merges two names of a person by itself: two people can
share a name, and a merge it guessed wrong would close one person's facts
with another's. This is the declaration that does it. From now on a fact
written about `name` in this end user's memory is a fact about the end
user, and the facts already written about `name` are read so at once
(their written words stay as they were). It is the alias the dashboard
makes (`POST /admin/aliases`), for the key's project and this end user.

`end_user` is the `user_id` exactly as written, percent-encoded as one
path segment. Declaring the same name again answers the same. 409 when
`name` is already declared for somebody else in this memory, 422 when it
is not a name.

There is no undo here: `DELETE /admin/aliases/{id}` removes the alias,
and the facts take back the names their words give; two open facts it
merged stay one, and a plan it closed stays closed.

## Path parameters

- `end_user` string, required

## Request body

- NameBody
  - `name` string, required: Another name of the end user, as the memories write it: a full name ("Maria Rossi") for the id `maria`.
  - `agent_id` string, nullable: The agent namespace whose memory the name is declared in; none for the end user's own memory.

## Response `201`

Successful Response

- NameResponse
  - `user_id` string, required
  - `name` string, required
  - `agent_id` string, nullable
  - `since` string, date-time, nullable

## Other responses

- `401`: `invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.
- `403`: `forbidden`: the key lacks the scope this operation needs; `message` names it.
- `409`: `conflict`: the name is already declared for somebody else in this end user's memory (the same name declared again for the same end user answers 201, as the first time).
- `413`: `payload_too_large`: the body is larger than 2,097,152 bytes, the most this route takes. Refused before it is read; nothing was done.
- `422`: `invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).
- `429`: `rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets.
- `500`: `internal_error`: the server failed on this request; `message` holds no detail of it.
- `503`: A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry.

---

[API](https://skmtc.dev/korely/apis/korely-agents-api.md) · [All operations](https://skmtc.dev/korely/apis/korely-agents-api/llms.txt) · [OpenAPI document](https://skmtc.dev/korely/apis/korely-agents-api/revisions/8a40bf09eca1?raw)