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

# OpenPayload Directory API

> Public identity, policy, Persona, and Application APIs

A Directory is the network's public identity lookup service. Your client can use it to answer questions such as “Which encryption key belongs to this recipient?”, “Where can I deliver a message?”, and “Is this device still active?”

Read-only requests are ordinary HTTP requests. Updates require a signature from a key already authorized by the DID.

<Note>
  Directory mutations use proof from the DID's root key or another authorized DID key. Account-owner pallet calls remain available to developers who interact with the chain directly, but they are not exposed as Directory HTTP routes.
</Note>

<Note>
  This reference documents only the public API contract. It excludes operational, diagnostic, test-only, and mesh-management interfaces. It does not describe OpenPayload's internal validation, persistence, signing, or chain-submission logic.
</Note>

## Base URL

Use the HTTPS URL provided by your OpenPayload 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="Personas" icon="globe" href="/api-reference/directory/personas/create-dns-challenge">
    Register, renew, transfer, and manage a unique DNS-backed organization or collective name.
  </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="/concepts/delivery-policies">
    Publish and resolve optional DID or Persona routing rules.
  </Card>

  <Card title="Applications" icon="code" href="/api-reference/directory/applications/get-policy">
    Register an Application, authorize its control targets, and read its independent policy.
  </Card>
</CardGroup>

## Start with a read-only request

You can resolve a DID without installing an SDK, creating an account, or holding a private key:

```bash theme={null}
curl --request GET \
  --url "https://directory.example.com/resolve/did%3Aopenpayload%3A1111111111111111111111"
```

Replace the hostname with a Directory operator's HTTPS URL and the sample DID with the identifier you need.

## Read requests and update requests

| Request type | What you need |
| - | - |
| Resolve a DID, alias, Persona, policy, or nonce | The public identifier |
| Resolve winning delivery behavior | A recipient and optional Persona and tag |
| Submit an authorized mutation | The identifier, current nonce where applicable, canonical public payload, and authorized signature set |

<Card title="Authorization guide" icon="signature" href="/guides/authorization">
  Learn what a nonce is and how a client signs an update without revealing its private key.
</Card>

## 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 or Persona, operation or extrinsic name, and transaction hash. Some DID endpoints also include 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, missing a required field, or violates a validated policy or constraint shape. |
| `403` | Authorization failed or a body identifier does not match the path. |
| `404` | The requested DID, Persona, policy, DNS challenge, or document component does not exist. |
| `409` | The request conflicts with existing or pending state, uses a stale nonce, or addresses an inactive Persona. |
| `422` | A published Persona DNS TXT value could not be verified. |
| `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, Personas, policy documents, tags, and service endpoints may become publicly discoverable.
</Warning>

## Policies are optional

A DID or Persona can exist without a delivery policy. `POST /delivery-policies/resolve` returns `200` with `applied: false` when no rule applies. Relays then use the recipient DID's ordinary service entries. Infrastructure failures and inactive Personas are errors and must not be treated as policy-free delivery.

<Card title="Delivery-policy resolution" icon="route" href="/api-reference/directory/policies/resolve">
  Resolve the winning Persona or DID rule from finalized chain state.
</Card>

## Straight to the point

```text theme={null}
Base URL: https://<operator-host>[:port]
Content-Type for JSON: application/json
Read success: usually 200 OK
Accepted mutation: usually 202 Accepted
DID paths: URL-encode the complete did:openpayload:... value
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.