> ## 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 Directory API

> Public API reference for Talaria decentralized identifiers

Use the Talaria Directory API to resolve decentralized identifiers (DIDs) and submit authorized changes to public DID records.

<Note>
  This reference documents only the public API contract.
</Note>

## Base URL

Use the HTTPS URL provided by your Talaria Directory operator.

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

The hostname in this documentation is a placeholder. Replace it with your operator-provided hostname. The API playground is disabled so examples cannot send requests to the placeholder.

Send JSON request bodies with the `Content-Type: application/json` header. URL-encode DIDs, aliases, and document component IDs when you place them in a path.

## API groups

<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 the root key.
  </Card>

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

## Submission behavior

Mutation endpoints return `202 Accepted` after the Directory accepts a request for processing. This status does not confirm final settlement.

Accepted submissions return a public receipt containing the affected DID, operation name, transaction hash, and a human-readable message.

## Errors

Newer endpoints return JSON errors with `error` and `message` fields. A `details` object appears only when the server has safe public context to return.

| Status | Meaning                                                            |
| ------ | ------------------------------------------------------------------ |
| `400`  | The request is malformed or missing a required field.              |
| `403`  | Authorization failed or a body identifier does not match the path. |
| `404`  | The requested DID or component does not exist.                     |
| `409`  | The request conflicts with existing or pending state.              |
| `425`  | A registration is awaiting confirmation.                           |
| `500`  | The service is unavailable or could not process the request.       |
| `502`  | An upstream submission or lookup failed.                           |

<Warning>
  Do not log private keys, signing material, or unredacted authorization payloads. Public keys, DIDs, aliases, policy documents, and service endpoints may become publicly discoverable.
</Warning>