# Asset class definitions Source: https://docs.settlemint.com/docs/api-reference/reference/asset-class-definitions List, create, read, update, and delete organisation asset class definitions through the DALP Platform API, CLI, and SDK. An asset class definition is a catalog entry that groups instrument templates and deployed assets under one label, such as `fixed-income`, `equity`, or a custom class your organisation adds. DALP seeds a set of system classes and lets each organisation add its own. Use these endpoints when an integration manages the asset class catalog directly, instead of through the Console. For the operator workflow and how classes feed asset creation, see [Instrument templates](/docs/operators/asset-creation/instrument-templates) and [Create a custom template](/docs/operators/asset-creation/custom-template). ## System and custom classes [#system-and-custom-classes] Each class carries an `isSystem` flag. * **System classes** are seeded by DALP and shared across organisations. Any caller with read access can list and read them, but they cannot be updated or deleted through this API. * **Custom classes** belong to the organisation that created them. Only that organisation can read, update, or delete its custom classes. A class is identified by its `id` and addressed by a `slug`. The slug is unique per organisation: two classes in the same organisation cannot share a name-derived or explicit slug. ## Endpoints [#endpoints] | Endpoint | Use it for | | ------------------------------------------------------ | -------------------------------------------------------- | | `GET /api/v2/settings/asset-class-definitions` | List asset class definitions in the active organisation. | | `POST /api/v2/settings/asset-class-definitions` | Create a custom asset class definition. | | `GET /api/v2/settings/asset-class-definitions/{id}` | Read one asset class definition. | | `PUT /api/v2/settings/asset-class-definitions/{id}` | Update a custom asset class definition. | | `DELETE /api/v2/settings/asset-class-definitions/{id}` | Delete a custom asset class definition. | 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, 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). ## Definition fields [#definition-fields] Each asset class definition returns these fields: | Field | Type | Description | | ---------------- | ---------------- | ------------------------------------------------------------------------ | | `id` | string | Stable identifier for the asset class definition. | | `name` | string | Display name, 1 to 255 characters. | | `description` | string or `null` | Optional description, up to 1000 characters. | | `slug` | string | URL-safe kebab-case identifier, unique within the organisation. | | `isSystem` | boolean | `true` for DALP-seeded system classes, `false` for organisation classes. | | `organizationId` | string or `null` | Owning organisation. `null` for shared system classes. | | `createdBy` | string or `null` | User who created the class. | | `createdAt` | string | Creation timestamp. | | `updatedAt` | string | Last update timestamp. | ## List classes [#list-classes] `GET /api/v2/settings/asset-class-definitions` returns the system classes plus the active organisation's custom classes. The list supports pagination, global search, sorting by `name`, `createdAt`, or `updatedAt`, and filtering by `isSystem`. Default sort is by `name`. Facets are returned for `isSystem` so a client can show system and custom counts side by side. ```bash curl --globoff "https://your-platform.example.com/api/v2/settings/asset-class-definitions?filter[isSystem]=false&sort=name" \ -H "x-api-key: YOUR_API_KEY" ``` ```json { "data": [ { "id": "f0c1a2b3-4d5e-6789-abcd-ef0123456789", "name": "Derivatives", "description": null, "slug": "derivatives", "isSystem": false, "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-class-definitions?filter[isSystem]=false&sort=name&page[offset]=0&page[limit]=50", "first": "/v2/settings/asset-class-definitions?filter[isSystem]=false&sort=name&page[offset]=0&page[limit]=50", "prev": null, "next": null, "last": "/v2/settings/asset-class-definitions?filter[isSystem]=false&sort=name&page[offset]=0&page[limit]=50" } } ``` ## Create a custom class [#create-a-custom-class] `POST /api/v2/settings/asset-class-definitions` creates a custom class for the active organisation. Send a `name`, an optional `description`, and an optional `slug`. If you omit `slug`, DALP derives it from `name` by converting to kebab-case. A supplied `slug` must already be kebab-case. ```bash curl -X POST "https://your-platform.example.com/api/v2/settings/asset-class-definitions" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Derivatives", "description": "Financial instruments whose value derives from underlying assets" }' ``` ```json { "data": { "id": "f0c1a2b3-4d5e-6789-abcd-ef0123456789", "name": "Derivatives", "description": "Financial instruments whose value derives from underlying assets", "slug": "derivatives", "isSystem": false, "organizationId": "org_123", "createdBy": "user_456", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "links": { "self": "/v2/settings/asset-class-definitions/f0c1a2b3-4d5e-6789-abcd-ef0123456789" } } ``` If the slug already exists for the organisation on create, the request returns `DALP-0480` with HTTP `409`. This also applies when the slug is auto-derived from `name` and that derived slug collides. Duplicate display names are accepted as long as the slug is distinct. Choose a different name or supply an explicit unique slug, or reuse the existing class. ## Read, update, and delete a class [#read-update-and-delete-a-class] `GET /api/v2/settings/asset-class-definitions/{id}` returns one class. The active organisation can read its own custom classes and any system class. `PUT /api/v2/settings/asset-class-definitions/{id}` updates `name`, `description`, or `slug` on a custom class. Send only the fields you want to change. A request with no changed fields returns the current class unchanged. `DELETE /api/v2/settings/asset-class-definitions/{id}` removes a custom class. System classes are read-only: an update returns `DALP-0156` and a delete returns `DALP-0155`, both with HTTP `409`. To diverge from a system class, create a custom class instead. ## Errors [#errors] | Error ID | Status | When it happens | Recovery | | ----------- | ------ | -------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `DALP-0480` | 409 | The slug collides with an existing class in the organisation. | Choose a different slug, or reuse the existing class. | | `DALP-0155` | 409 | A delete targeted a system class. | System classes cannot be deleted. Remove a custom class instead. | | `DALP-0156` | 409 | An update targeted a system class. | System classes cannot be modified. Create a custom class instead. | | `DALP-0088` | 404 | A read could not find the class in the organisation or system scope. | Verify the ID and that the class belongs to your organisation. | | `DALP-0089` | 404 | A delete could not find a custom class owned by the organisation. | Verify the ID and that the class belongs to your organisation. | | `DALP-0090` | 404 | An update could not find the class, for example after a concurrent delete. | Re-read the class list and retry against a current ID. | For the full catalog, see the [Platform API error reference](/docs/api-reference/errors/platform-api-error-reference). ## CLI [#cli] The `dalp` CLI exposes the same operations through the `settings` command group. ```bash dalp settings asset-class-definitions-list dalp settings asset-class-definitions-read dalp settings asset-class-definitions-create --name "Derivatives" --description "..." --slug derivatives dalp settings asset-class-definitions-update --name "Updated name" dalp settings asset-class-definitions-delete ``` ## SDK [#sdk] The SDK exposes the same operations under `settings.assetClassDefinitions`. ```ts fixture=dalp-client const list = await client.settings.assetClassDefinitions.list({ query: {} }); const created = await client.settings.assetClassDefinitions.create({ body: { name: "Derivatives", description: "..." }, }); const one = await client.settings.assetClassDefinitions.read({ params: { id: created.data.id } }); await client.settings.assetClassDefinitions.update({ params: { id: created.data.id }, body: { name: "Updated name" }, }); await client.settings.assetClassDefinitions.delete({ params: { id: created.data.id } }); ``` 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) shows how asset classes group reusable asset setup patterns. * [Create a custom template](/docs/operators/asset-creation/custom-template) covers the operator workflow that selects an asset class. * [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.