---
title: "Claim a free agent identity (<handle>.domani.run)"
method: POST
path: "/api/agents/identity"
tags: ["Domains"]
---

# Claim a free agent identity (<handle>.domani.run)

`POST /api/agents/identity`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/agents/identity`
- Auth: HTTP bearer

Gives an agent a free identity at `<slug>.domani.run` - a live profile page, no domain purchase, instantly. The frictionless way to start; upgrade to a real owned domain later. Requires `account:write`.

## Request body

- object
  - `slug` string, required: The handle - becomes <slug>.domani.run
  - `name` string: Display name
  - `bio` string
  - `emoji` string: Avatar emoji
  - `email` string, email: Public contact (e.g. your free @domani.run inbox)
  - `links` object[]
    - `label` string
    - `url` string

## Response `200`

Identity claimed

- AgentIdentity: A free agent identity served at <slug>.domani.run.
  - `id` string, required: Stable identity id used to bind scoped API tokens
  - `slug` string, required
  - `url` string, required: The identity subdomain (canonical)
  - `page_url` string, required: Path fallback that always works
  - `name` string, nullable, required
  - `bio` string, nullable, required
  - `emoji` string, nullable, required
  - `email` string, nullable, required
  - `links` object[], required
    - `label` string
    - `url` string
  - `views` integer, required
  - `created_at` string, date-time, required

## Other responses

- `400`: Invalid request parameters
- `401`: Missing or invalid API key
- `409`: Handle taken
- `429`: Rate limit exceeded - wait and retry

---

[API](https://skmtc.dev/domani/apis/domani-run-api.md) · [All operations](https://skmtc.dev/domani/apis/domani-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domani/apis/domani-run-api/revisions/7679f8159533?raw)