Directory topic schemes API reference

A topic scheme defines a kind of verifiable claim, such as a Know Your Customer result or an accredited-investor attestation, and the data shape that claim carries. DALP compliance checks reference these schemes when they decide whether a transfer or other gated operation may proceed. An auditor or compliance lead needs an authoritative view of which topic schemes the platform recognises and exactly what data shape each one defines. These endpoints provide that platform-wide view.

The directory topic scheme registry is the platform-wide (global) tier. Schemes registered here are inherited by the systems beneath them, so a single scheme can apply across many systems at once. Each scheme record reports inheritedBySystemsCount. A reviewer reads that count to see how far a scheme reaches before anyone changes it.

This surface is read-only. It lists and reads topic schemes. It does not register, edit, or remove them.

How this differs from system claim topics

DALP resolves topic schemes across tiers: the platform-wide directory and each system. These endpoints read the platform-wide directory tier only. A scheme that exists here is the global definition that downstream systems inherit, unless a system has registered its own scheme under the same numeric topic id.

Required role

Reading the platform-wide directory requires the platform admin role. These endpoints sit above the per-system permission model, so a system-scoped role cannot call them.

Set the standard request headers before calling these endpoints. See Request headers.

Endpoints

The list response uses the collection envelope with data, meta, and pagination links. The read response uses the single-resource envelope with data and links.self.

Topic scheme fields

The list and read endpoints return the same scheme record.

The signature is the contract that downstream claims must satisfy. Two schemes that share a topicId but disagree on signature describe incompatible claim shapes for the same topic. That mismatch is what isShadowed flags.

Shadowed schemes

A scheme is shadowed when a child system has registered the same numeric topicId under a different signature. The global definition still stands, but at least one system reads that topic with a conflicting claim shape. A reviewer treats isShadowed: true as a signal to reconcile the system-tier registration before relying on claims for that topic, because a claim valid under one signature does not validate under the other.

List directory topic schemes

GET /api/v2/directory/topic-schemes returns the schemes registered in the platform-wide directory, ordered by name.

The list supports pagination, sorting by name or topicId, and filtering by topicId, name, and signature. It also supports global search with filter[q], which matches across the name, signature, and topic id in one query.

curl --globoff "https://your-platform.example.com/api/v2/directory/topic-schemes?filter[name]=Customer&sort=name" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": [
    {
      "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F#1",
      "topicId": "1",
      "name": "Know Your Customer",
      "signature": "(string)",
      "registry": {
        "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
      },
      "isShadowed": false,
      "inheritedBySystemsCount": 3
    }
  ],
  "meta": {
    "total": 1,
    "facets": {}
  },
  "links": {
    "self": "/v2/directory/topic-schemes?page[offset]=0&page[limit]=50",
    "first": "/v2/directory/topic-schemes?page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/directory/topic-schemes?page[offset]=0&page[limit]=50"
  }
}

The list returns 50 schemes per page by default, up to 200. Use page[offset] and page[limit] to page through larger registries. The name filter matches case-insensitively, so filter[name]=customer and filter[name]=Customer return the same rows.

Read one topic scheme

GET /api/v2/directory/topic-schemes/{name} returns a single scheme by its name. The path segment is the scheme name, not the numeric topic id, and the lookup is case-sensitive with no normalization.

curl "https://your-platform.example.com/api/v2/directory/topic-schemes/Know%20Your%20Customer" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": {
    "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F#1",
    "topicId": "1",
    "name": "Know Your Customer",
    "signature": "(string)",
    "registry": {
      "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
    },
    "isShadowed": false,
    "inheritedBySystemsCount": 3
  },
  "links": {
    "self": "/v2/directory/topic-schemes/Know%20Your%20Customer"
  }
}

URL-encode names that contain spaces or other reserved characters, as shown above. The endpoint returns DALP-0619 with status 404 when no scheme matches the name on the global registry. Confirm the name and that the scheme was registered before retrying. Because the read reflects the indexed registry, a recently registered scheme may need a moment for indexing to catch up.

When the global registry is unavailable

Both endpoints resolve the platform-wide topic scheme registry from the active network's directory before reading. If the directory address is missing for the active network, or the indexer has not yet processed the global registry, they return DALP-0618 with status 404. Confirm the platform's directory address is configured for the active network and that indexing has caught up, then retry.

When to use it

Use these endpoints when you need to:

• Produce an audit list of every claim topic scheme the platform recognises.
• Confirm the exact claim signature a topic enforces before relying on claims that use it.
• Spot shadowed topics, where a system has redefined a global topic with a different claim shape, through isShadowed.
• Measure how far a scheme reaches across systems through inheritedBySystemsCount before a change.

To see which trusted issuers may attest each topic, use the Directory trusted issuers API.