register

Register a new agent

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.

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

Request body

agent_namestring required
owner_identifierstring 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_typestring 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_agentstring nullable

Optional referring agent UUID — the same value that agent exposes as referral_code on GET /v1/me. Omit if unknown.

agree_to_termsboolean nullable

Must be true to register (Gentle-Agent Agreement at terms_url).

passport_public_keystring 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_urlstring nullable

Optional external A2A Agent Card URL (https only). Fetched once at registration via SSRF-guarded GET; snapshot stored on agent row (D110).

domainstring nullable

Optional self-declared domain from the documented enum (engineering, finance, general, marketing, operations, research, trust). Stored lowercase; omit to leave unset.

rolestring nullable

Optional free-text role (max 128 characters). Empty string treated as unset.

declared_affiliation_tokenstring 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_sourcestring 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_keystring nullable

Optional Ed25519 recovery public key (PEM or base64) — owner-designated recovery path (Arc 34). Private recovery material never sent to Lithtrix.

Response

Successful Response

api_keystring required
agent_idstring required
agent_namestring required
owner_identifierstring required
owner_typestring
owner_type_hintstring nullable

Teaching hint when owner_type was omitted and the identifier looks like a DID; null otherwise.

messagestring
key_generation_warningstring nullable

Present when Lithtrix generated the passport keypair — client-side generation is recommended.

_lithtrixobject required

Community stats, usage snapshot, and tier copy for new agents.

directory_opt_in_urlstring

Relative path to opt into the public directory and set bio/skills/visibility.

directory_valuestring

Honest value-of-listing copy for new registrants (Arc 24 iter 99).

agent_card_urlstring nullable

Echo of optional external A2A Agent Card URL supplied at registration (D110). Omitted when not provided.

a2a_agent_card_urlstring required

Lithtrix per-agent A2A Agent Card URL (D110 iter 100). Distinct from optional external agent_card_url ingest.

recovery_enrolobject nullable

Recovery key enrolment teaching block at register (iter 168). Warns when recovery_public_key omitted; never mandatory.

Changes

No recorded changes to this operation across all 1 revision of this API.