# Instrument templates API Source: https://docs.settlemint.com/docs/api-reference/reference/instrument-templates List, read, create, update, publish, and delete instrument templates through the DALP Platform API and SDK, and hide or show templates per organisation with the isHidden filter and toggle. An instrument template is a reusable issuance pattern for the Asset Designer. Each template groups an asset class, a deployable asset type, required token features, feature defaults, and the metadata fields DALP collects during issuance. DALP seeds a set of system templates and lets each organisation add its own. Use these endpoints when an integration manages templates directly, instead of through the Console. For the operator workflow, see [Instrument templates](/docs/operators/asset-creation/instrument-templates) and [Create a custom template](/docs/operators/asset-creation/custom-template). ## System and organisation templates [#system-and-organisation-templates] Each template carries an `isSystem` flag. * **System templates** are seeded by DALP and shared across organisations. Any caller with read access can list and read them, but their definition cannot be changed through this API. * **Organisation templates** belong to the organisation that created them. Only that organisation can read, update, publish, or delete its own templates. A template is identified by its `id` and addressed by a `slug`. The slug is unique per organisation. A template is created as a draft and becomes immutable in key fields once published. ## Endpoints [#endpoints] | Endpoint | Use it for | | -------------------------------------------------------- | -------------------------------------------------------- | | `GET /api/v2/settings/asset-type-templates` | List instrument templates in the active organisation. | | `POST /api/v2/settings/asset-type-templates` | Create a draft instrument template. | | `GET /api/v2/settings/asset-type-templates/{id}` | Read one instrument template. | | `PUT /api/v2/settings/asset-type-templates/{id}` | Update a template, or hide and show it per organisation. | | `PUT /api/v2/settings/asset-type-templates/{id}/publish` | Publish a draft template. | | `DELETE /api/v2/settings/asset-type-templates/{id}` | Delete a template. | Read responses use the DALP single-resource envelope with `data` and `links.self`. List responses use the collection envelope with `data`, `meta`, and pagination `links`. Delete responses return `{ "data": null }`. ## Required roles [#required-roles] | Operation | Roles (any of) | | ------------------------------- | ---------------------------------------- | | List, read | `admin`, `systemManager`, `tokenManager` | | Create, update, publish, delete | `admin`, `systemManager` | Set the participant and wallet context with the standard request headers before calling these endpoints. See [Request headers](/docs/api-reference/reference/request-headers). ## Template fields [#template-fields] Each instrument template returns these fields: | Field | Type | Description | | ------------------- | ---------------- | ---------------------------------------------------------------------------------------------- | | `id` | string | Stable identifier for the template. | | `name` | string | Display name, 1 to 255 characters. | | `slug` | string | URL-safe identifier, unique within the organisation. | | `description` | string or `null` | Optional description. | | `assetClass` | string | Slug of the asset class this template belongs to. | | `assetClassId` | string or `null` | Owning asset class identifier. `null` for templates that use the system class mapping. | | `typeId` | string | Concrete asset type slug, such as `bond` or `deposit`. | | `baseAssetType` | string | Deployable base asset type that determines pricing fields. | | `isSystem` | boolean | `true` for DALP-seeded system templates, `false` for organisation templates. | | `isDraft` | boolean | `true` while the template is a draft, `false` once published. System templates are not drafts. | | `isHidden` | boolean | `true` when the active organisation has hidden this template. Computed per organisation. | | `hiddenFromSidebar` | boolean | `true` when the template is hidden from the Asset Designer sidebar. Mutable on all templates. | | `version` | number | Increments on each definition change. Visibility changes do not bump the version. | | `requiredFeatures` | array | Token features the template requires. | | `metadataSchema` | object or `null` | Metadata fields the Asset Designer collects during issuance. | | `featureConfig` | object or `null` | Default feature settings the template applies. | | `organizationId` | string or `null` | Owning organisation. `null` for shared system templates. | | `createdBy` | string or `null` | User who created the template. | | `createdAt` | string | Creation timestamp. | | `updatedAt` | string | Last update timestamp. | ## List templates [#list-templates] `GET /api/v2/settings/asset-type-templates` returns the system templates plus the active organisation's templates. The list supports pagination, global search, sorting by `name`, `createdAt`, or `updatedAt`, and filtering by `assetClass`, `typeId`, `isSystem`, `isDraft`, or `isHidden`. Default sort is by `name`, with system templates ordered first. By default the list returns both visible and hidden templates. Add `filter[isHidden]=false` to return only the templates visible to the active organisation, or `filter[isHidden]=true` to return only the hidden set. `isHidden` is filterable but not sortable, because it is computed per organisation rather than stored on the template. ```bash curl --globoff "https://your-platform.example.com/api/v2/settings/asset-type-templates?filter[isHidden]=false&sort=name" \ -H "x-api-key: YOUR_API_KEY" ``` ```json { "data": [ { "id": "f0c1a2b3-4d5e-6789-abcd-ef0123456789", "name": "Senior secured bond", "slug": "senior-secured-bond", "description": null, "assetClass": "fixed-income", "assetClassId": null, "typeId": "bond", "baseAssetType": "bond", "isSystem": false, "isDraft": false, "isHidden": false, "hiddenFromSidebar": false, "version": 2, "requiredFeatures": [], "metadataSchema": null, "featureConfig": null, "organizationId": "org_123", "createdBy": "user_456", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" } ], "meta": { "total": 1, "facets": { "isSystem": [{ "value": "false", "count": 1 }] } }, "links": { "self": "/v2/settings/asset-type-templates?filter[isHidden]=false&sort=name&page[offset]=0&page[limit]=50", "first": "/v2/settings/asset-type-templates?filter[isHidden]=false&sort=name&page[offset]=0&page[limit]=50", "prev": null, "next": null, "last": "/v2/settings/asset-type-templates?filter[isHidden]=false&sort=name&page[offset]=0&page[limit]=50" } } ``` ## Create, read, and delete [#create-read-and-delete] `POST /api/v2/settings/asset-type-templates` creates a draft template. Send a `name`, a `typeId`, a `baseAssetType`, and an optional `description`, `assetClassId`, `requiredFeatures`, `metadataSchema`, or `featureConfig`. DALP derives the slug from the name. `GET /api/v2/settings/asset-type-templates/{id}` returns one template. The active organisation can read its own templates and any system template. `DELETE /api/v2/settings/asset-type-templates/{id}` removes an organisation template. `PUT /api/v2/settings/asset-type-templates/{id}/publish` transitions a draft to published. A published template locks its `typeId` and `baseAssetType` so existing deployments keep working. ## Update a template [#update-a-template] `PUT /api/v2/settings/asset-type-templates/{id}` updates an organisation template. Send only the fields you want to change. Any definition change bumps `version`. A published template cannot change its `typeId` or `baseAssetType`. System templates are read-only for their definition. A request that changes name, description, type, asset class, features, or metadata on a system template returns `DALP-0161`. Only visibility preferences can be changed on a system template. ## Hide and show a template [#hide-and-show-a-template] Hiding a template removes it from the Asset Designer selection step so operators can no longer pick it for new assets. Assets already issued from the template are unaffected. Visibility is tracked per organisation: when you hide a template, only your organisation's visible-only views drop it, and other organisations are unaffected. Send `isHidden` on the update endpoint to toggle visibility. The CLI does not expose this toggle; use the API or SDK. Unlike definition edits, visibility can be changed on any template the organisation can see, including shared system and default templates: * `isHidden: true` hides the template for the active organisation. * `isHidden: false` shows it again. ```bash curl -X PUT "https://your-platform.example.com/api/v2/settings/asset-type-templates/f0c1a2b3-4d5e-6789-abcd-ef0123456789" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "isHidden": true }' ``` The response returns the template with its updated `isHidden` value. A visibility toggle does not bump `version`. You can combine `isHidden` with definition fields in one request on an organisation template. On a system template, send `isHidden` alone, because definition fields are rejected. To list only the templates your integration should offer for issuance, request the visible published set with `filter[isHidden]=false&filter[isDraft]=false`. To review and restore hidden templates, request `filter[isHidden]=true`. ## Errors [#errors] | Error ID | Status | When it happens | Recovery | | ----------- | ------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | `DALP-0091` | 404 | A read, update, publish, or delete could not find the template in scope. | Verify the ID, ownership scope, and indexing state, then retry. | | `DALP-0161` | 409 | A definition edit targeted a system template. | System definitions cannot be modified. Create an organisation template, or send only `isHidden`. | | `DALP-0463` | 409 | The name collides with an existing organisation template. | Choose a unique template name, or update the existing template instead. | For the full catalog, see the [Platform API error reference](/docs/api-reference/errors/platform-api-error-reference). ## SDK [#sdk] The SDK exposes these operations under `settings.assetTypeTemplates`. Hiding and showing a template is available through the API and SDK. ```ts fixture=dalp-client const list = await client.settings.assetTypeTemplates.list({ query: {} }); const visibleOnly = await client.settings.assetTypeTemplates.list({ query: { filter: { isHidden: "false" } }, }); const one = await client.settings.assetTypeTemplates.read({ params: { id: list.data[0].id } }); await client.settings.assetTypeTemplates.update({ params: { id: one.data.id }, body: { isHidden: true }, }); ``` SDK errors expose the same `id`, `status`, and `retryable` fields as the REST envelope. See the [SDK reference](/docs/api-reference/reference/sdk) and [error handling](/docs/api-reference/errors/error-handling). ## Related pages [#related-pages] * [Instrument templates](/docs/operators/asset-creation/instrument-templates) covers the operator workflow, including the Asset Designer and template visibility switches. * [Asset class definitions](/docs/api-reference/reference/asset-class-definitions) manages the asset class catalog that groups templates, with the same per-organisation visibility model. * [Operational integration patterns](/docs/api-reference/reference/operational-integration-patterns) covers discovering deployed tokens and configured asset classes. * [Platform API error reference](/docs/api-reference/errors/platform-api-error-reference) covers structured error handling.