---
title: "Register a new agent"
method: POST
path: "/v1/register"
tags: ["register"]
---

# Register a new agent

`POST /v1/register`

## Request

- Base URL: `https://api.lithtrix.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.lithtrix.ai/v1/register`
- Auth: none declared

Create an `agents` row and return a one-time `ltx_*` API key (SHA-256 stored). The same `agent_name` + `owner_identifier` pair returns HTTP 409. On **201**, also returns an Arc 21 **passport** (Ed25519). **Recommended:** supply **passport_public_key** (client-generated) so Lithtrix never sees your private key. When omitted, Lithtrix generates the keypair (labeled fallback): the **private** key appears **only** in this response and **`key_generation_warning`** recommends client-side generation.

## Request body

- RegisterRequest: Body for `POST /v1/register`.
  - `agent_name` string, required
  - `owner_identifier` string, required: Contact email (recommended): a working email address you control. Never shown publicly. Not required to register, keep memory, earn trust, or stay safe. Used today for storage-deletion warnings and auto top-up failure notices when stored as owner_type email.
  - `owner_type` string, nullable: Optional. One of: email, oauth, did, wallet, uuid, agent. When omitted, Lithtrix stores email if the value is email-shaped, otherwise unspecified (DID-shaped values may return owner_type_hint on 201). Clients cannot send unspecified.
  - `referral_agent` string, nullable: Optional referring agent UUID — the same value that agent exposes as `referral_code` on `GET /v1/me`. Omit if unknown.
  - `agree_to_terms` boolean, nullable: Must be true to register (Gentle-Agent Agreement at terms_url).
  - `passport_public_key` string, nullable: Optional PEM-encoded Ed25519 public key (SPKI) or base64 raw public bytes — recommended client-side path. Lithtrix stores public material only; omit for server-generated keypair (labeled fallback; 201 includes key_generation_warning and one-time private_key).
  - `agent_card_url` string, nullable: Optional external A2A Agent Card URL (https only). Fetched once at registration via SSRF-guarded GET; snapshot stored on agent row (D110).
  - `domain` string, nullable: Optional self-declared domain from the documented enum (engineering, finance, general, marketing, operations, research, trust). Stored lowercase; omit to leave unset.
  - `role` string, nullable: Optional free-text role (max 128 characters). Empty string treated as unset.
  - `declared_affiliation_token` string, nullable: Optional pre-shared token issued out-of-band for attestable affiliation at registration. When valid, overrides heuristic affiliation classification. Invalid or unknown tokens are ignored (no error). Never grants external affiliation.
  - `registration_source` string, nullable: Optional self-declared registration channel tag (max 64 characters). Convention is channel:page, e.g. langgraph:readme or langgraph:docs — not a fixed enum, unrecognized values are stored as-is. Honesty-based attribution for D160-1 metrics; omit for organic traffic rather than inventing a value.
  - `recovery_public_key` string, nullable: Optional Ed25519 recovery public key (PEM or base64) — owner-designated recovery path (Arc 34). Private recovery material never sent to Lithtrix.

## Response `201`

Successful Response

- Register201Response: HTTP 201 body for ``POST /v1/register`` (OpenAPI + response validation).
  - `api_key` string, required
  - `agent_id` string, required
  - `agent_name` string, required
  - `owner_identifier` string, required
  - `owner_type` string
  - `owner_type_hint` string, nullable: Teaching hint when owner_type was omitted and the identifier looks like a DID; null otherwise.
  - `message` string
  - `key_generation_warning` string, nullable: Present when Lithtrix generated the passport keypair — client-side generation is recommended.
  - `passport` PassportRegistrationBlock, required: Arc 21 — passport material returned **once** on ``POST /v1/register`` (private key never stored server-side).
    - `did` string, required: Deterministic DID, e.g. ``did:lithtrix:<agent_uuid>``.
    - `public_key` string, required: PEM-encoded Ed25519 public key.
    - `private_key` string, nullable: PEM-encoded Ed25519 private key — **shown only in server-generated 201 responses**.
    - `private_key_notice` string, nullable: Explains absent private_key when operator-derived at registration.
    - `derivation_method` string: ``server_generated`` (fallback) or ``operator_derived`` when ``passport_public_key`` was supplied.
    - `capabilities` PassportCapabilityPublicBlock, required: Split capability surface returned on passports and GET /v1/me (D88 — never fuse with verified).
      - `verified` string[], required: Lithtrix-derived lithtrix:* capability URIs (scoped keys + tier).
      - `self_reported` string[], required: Operator-declared capability strings stored on the passport (not audited by Lithtrix).
      - `self_reported_notice` string, required: Mandatory disclaimer distinguishing self_reported strings from lithtrix:verified URIs.
    - `endpoint` string, nullable: Reserved for agent endpoint URL; null until wired in a later iter.
  - `_lithtrix` object, required: Community stats, usage snapshot, and tier copy for new agents.
  - `directory_opt_in_url` string: Relative path to opt into the public directory and set bio/skills/visibility.
  - `directory_value` string: Honest value-of-listing copy for new registrants (Arc 24 iter 99).
  - `agent_card_url` string, nullable: Echo of optional external A2A Agent Card URL supplied at registration (D110). Omitted when not provided.
  - `a2a_agent_card_url` string, required: Lithtrix per-agent A2A Agent Card URL (D110 iter 100). Distinct from optional external agent_card_url ingest.
  - `recovery_enrol` object, nullable: Recovery key enrolment teaching block at register (iter 168). Warns when recovery_public_key omitted; never mandatory.

## Other responses

- `422`: Validation Error

---

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