> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talaria.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Talaria API reference

> Build with Talaria's public Directory API

Talaria provides a public Directory API for resolving decentralized identifiers (DIDs) and submitting authorized updates to public DID records.

Use this reference to create an identity, register its DID document, resolve public records, and manage aliases, document components, devices, and delivery policies.

<Note>
  These docs cover only the public API contract. They exclude operational interfaces and Talaria's internal validation, persistence, signing, routing, and chain implementation.
</Note>

## Start building

<CardGroup cols={2}>
  <Card title="Create your first DID" icon="rocket" href="/quickstart">
    Generate an Ed25519 keypair, DID document, and signed registration request from Bash or Python.
  </Card>

  <Card title="Directory API overview" icon="book-open" href="/talaria-directory-api">
    Learn about the public endpoint groups, submission behavior, and error format.
  </Card>
</CardGroup>

## Explore the API

<CardGroup cols={2}>
  <Card title="DIDs" icon="fingerprint" href="/api-reference/directory/dids/resolve">
    Resolve, register, and update public DID records.
  </Card>

  <Card title="Aliases" icon="at" href="/api-reference/directory/aliases/add-alias">
    Add, update, and remove public aliases.
  </Card>

  <Card title="DID documents" icon="file-certificate" href="/api-reference/directory/document/add-verification-method">
    Manage verification methods, authentication, key agreements, services, and root keys.
  </Card>

  <Card title="Delivery policies" icon="route" href="/api-reference/directory/policies/set-recipient">
    Set public recipient, tag, and persona delivery policies.
  </Card>
</CardGroup>

## Base URL

Your Talaria Directory operator provides the HTTPS base URL for API requests:

```text theme={null}
https://directory.example.com
```

The hostname in these docs is a placeholder. Replace it with the hostname supplied by your operator.

## Request lifecycle

1. Generate an Ed25519 keypair and a Base58 Talaria DID.
2. Build a public DID document that contains the public key.
3. Sign the registration request with the private key.
4. Submit the request to `POST /register-did`.
5. Resolve the DID until its `registration_status` is `confirmed`.

<Warning>
  Never send your private key to the Directory. Store it securely and submit only public keys, signatures, and public DID document data.
</Warning>