> For the complete documentation index, see [llms.txt](https://knowledgebase.fabricdata.com/studio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.fabricdata.com/studio/integrations-and-apis/origin-studio-production-api/datasets.md).

# Datasets

Manage a tenant's datasets. A dataset is an ordered list of items that limits a field's values, such as genres or ratings. Every tenant gets the shared system datasets and can add its own.

## Get datasets

> Lists the tenant's datasets: the shared system datasets and the tenant's own.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Datasets","description":"Manage a tenant's datasets. A dataset is an ordered list of items that limits a field's values, such as genres or ratings. Every tenant gets the shared system datasets and can add its own."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"GetDatasetsResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IGetDatasetsResponse","description":"All datasets in the tenant, with their attributes and relationship links.","type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Dataset"},"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"}},"additionalProperties":false},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}},"required":["data","jsonapi"],"additionalProperties":false},"Dataset":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDataset","description":"A dataset: a controlled vocabulary or lookup list that constrains field values. A localized dataset keys its items by locale.","allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"attributes":{"allOf":[{"$ref":"#/components/schemas/DatasetAttributes"},{"$ref":"#/components/schemas/BaseResourceAttributes"}],"additionalProperties":false},"meta":{"type":"object","properties":{"tenantId":{"type":"string"},"allowCustomItems":{"type":"boolean","description":"Whether users can add, update or delete items. When `false`, the dataset is locked: users can't change items, and only Fabric manages them."}},"additionalProperties":false},"relationships":{"type":"object","properties":{"tenant":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"links":{"type":"object","properties":{"related":{"type":"string"}},"required":["related"],"additionalProperties":false}},"additionalProperties":false},"items":{"type":"object","properties":{"links":{"type":"object","properties":{"related":{"type":"string"}},"required":["related"],"additionalProperties":false}},"additionalProperties":false}},"required":["tenant"],"additionalProperties":false}},"required":["attributes","meta"],"additionalProperties":false}]},"BaseResource":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResource","description":"A resource identifier. Every resource object carries a unique `id` and a `type`, the resource type name such as `records` or `contributors`.","type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"DatasetAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDatasetAttributes","description":"Attributes of a dataset.","type":"object","additionalProperties":false,"properties":{"dataSource":{"type":"string","description":"Who owns the dataset.\n- `fabric`: system-provisioned.\n- `custom`: tenant-created.","enum":["fabric","custom"]},"label":{"type":"string","description":"Display name."},"localized":{"type":"boolean","description":"When `true`, the dataset keys its items by locale."},"availableLocales":{"type":"array","description":"Locales a localized dataset supports.","items":{"type":"string"}},"key":{"type":"string","description":"Machine-readable identifier."},"tenantId":{"type":"string","description":"Tenant that owns the dataset."},"allowCustomItems":{"type":"boolean","description":"Whether tenants can add, update or delete items. When `false`, the dataset is locked and accepts no item changes."}},"required":["dataSource","label","key"]},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Timestamps on every resource's attributes, as ISO 8601 date-times. `created` marks the resource's creation; `updated` marks its last change.","type":"object","additionalProperties":false,"required":["created","updated"],"properties":{"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/datasets":{"get":{"summary":"Get datasets","operationId":"datasetFindMany","description":"Lists the tenant's datasets: the shared system datasets and the tenant's own.","tags":["Datasets"],"parameters":[{"name":"filter.label","in":"query","required":false,"style":"form","explode":false,"schema":{"type":"string"},"description":"Only datasets whose label contains this text, ignoring case, such as `filter.label=My Label`."},{"name":"filter.id","in":"query","required":false,"style":"form","explode":false,"schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"One or more dataset IDs."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetDatasetsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create a dataset

> Creates a dataset for the current tenant. \`key\` must be unique in the tenant. For locale-specific items, set \`localized: true\`. Add items afterwards with \`datasetAtomicOperations\`.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Datasets","description":"Manage a tenant's datasets. A dataset is an ordered list of items that limits a field's values, such as genres or ratings. Every tenant gets the shared system datasets and can add its own."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"CreateDatasetRequest":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDatasetCreateRequest","description":"Creates a dataset. Add its items afterwards with `datasetAtomicOperations`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"},"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"key":{"type":"string","description":"Unique key for the dataset"},"label":{"type":"string","description":"Label of the dataset"},"dataSource":{"type":"string","description":"Who owns the dataset.\n- `custom`: tenant-created.\n- `fabric`: system-provisioned.","enum":["custom","fabric"]},"localized":{"type":"boolean","description":"When `true`, each item has a `locale`."}},"required":["key","label","dataSource"],"additionalProperties":false}},"required":["type","attributes"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Audit metadata for a write request. `audit.source` names the surface that sent it, such as `studio-web`, `studio-mcp`, `api` or `system`; `audit.reason` is a free-text justification.","type":"object","additionalProperties":false,"properties":{"audit":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string","maxLength":64},"reason":{"type":"string","maxLength":256}}}}},"CreateDatasetResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDatasetCreateResponse","description":"The new dataset, with its server-assigned ID, attributes and relationship links.","type":"object","required":["data","links","jsonapi"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Dataset"},"links":{"type":"object","properties":{"self":{"type":"string"}},"required":["self"]},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Dataset":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDataset","description":"A dataset: a controlled vocabulary or lookup list that constrains field values. A localized dataset keys its items by locale.","allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"attributes":{"allOf":[{"$ref":"#/components/schemas/DatasetAttributes"},{"$ref":"#/components/schemas/BaseResourceAttributes"}],"additionalProperties":false},"meta":{"type":"object","properties":{"tenantId":{"type":"string"},"allowCustomItems":{"type":"boolean","description":"Whether users can add, update or delete items. When `false`, the dataset is locked: users can't change items, and only Fabric manages them."}},"additionalProperties":false},"relationships":{"type":"object","properties":{"tenant":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"links":{"type":"object","properties":{"related":{"type":"string"}},"required":["related"],"additionalProperties":false}},"additionalProperties":false},"items":{"type":"object","properties":{"links":{"type":"object","properties":{"related":{"type":"string"}},"required":["related"],"additionalProperties":false}},"additionalProperties":false}},"required":["tenant"],"additionalProperties":false}},"required":["attributes","meta"],"additionalProperties":false}]},"BaseResource":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResource","description":"A resource identifier. Every resource object carries a unique `id` and a `type`, the resource type name such as `records` or `contributors`.","type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"DatasetAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDatasetAttributes","description":"Attributes of a dataset.","type":"object","additionalProperties":false,"properties":{"dataSource":{"type":"string","description":"Who owns the dataset.\n- `fabric`: system-provisioned.\n- `custom`: tenant-created.","enum":["fabric","custom"]},"label":{"type":"string","description":"Display name."},"localized":{"type":"boolean","description":"When `true`, the dataset keys its items by locale."},"availableLocales":{"type":"array","description":"Locales a localized dataset supports.","items":{"type":"string"}},"key":{"type":"string","description":"Machine-readable identifier."},"tenantId":{"type":"string","description":"Tenant that owns the dataset."},"allowCustomItems":{"type":"boolean","description":"Whether tenants can add, update or delete items. When `false`, the dataset is locked and accepts no item changes."}},"required":["dataSource","label","key"]},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Timestamps on every resource's attributes, as ISO 8601 date-times. `created` marks the resource's creation; `updated` marks its last change.","type":"object","additionalProperties":false,"required":["created","updated"],"properties":{"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/datasets":{"post":{"summary":"Create a dataset","operationId":"datasetCreateOne","description":"Creates a dataset for the current tenant. `key` must be unique in the tenant. For locale-specific items, set `localized: true`. Add items afterwards with `datasetAtomicOperations`.","tags":["Datasets"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDatasetRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDatasetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a dataset

> Returns one dataset with attributes such as \`label\`, \`key\`, \`localized\` and \`allowCustomItems\`, plus a link to its items.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Datasets","description":"Manage a tenant's datasets. A dataset is an ordered list of items that limits a field's values, such as genres or ratings. Every tenant gets the shared system datasets and can add its own."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"GetDatasetResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IGetDatasetResponse","description":"One dataset, with its attributes, relationship links and a self link.","type":"object","required":["data","links","jsonapi"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Dataset"},"links":{"type":"object","required":["self"],"properties":{"self":{"type":"string"}},"additionalProperties":false},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Dataset":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDataset","description":"A dataset: a controlled vocabulary or lookup list that constrains field values. A localized dataset keys its items by locale.","allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"attributes":{"allOf":[{"$ref":"#/components/schemas/DatasetAttributes"},{"$ref":"#/components/schemas/BaseResourceAttributes"}],"additionalProperties":false},"meta":{"type":"object","properties":{"tenantId":{"type":"string"},"allowCustomItems":{"type":"boolean","description":"Whether users can add, update or delete items. When `false`, the dataset is locked: users can't change items, and only Fabric manages them."}},"additionalProperties":false},"relationships":{"type":"object","properties":{"tenant":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"links":{"type":"object","properties":{"related":{"type":"string"}},"required":["related"],"additionalProperties":false}},"additionalProperties":false},"items":{"type":"object","properties":{"links":{"type":"object","properties":{"related":{"type":"string"}},"required":["related"],"additionalProperties":false}},"additionalProperties":false}},"required":["tenant"],"additionalProperties":false}},"required":["attributes","meta"],"additionalProperties":false}]},"BaseResource":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResource","description":"A resource identifier. Every resource object carries a unique `id` and a `type`, the resource type name such as `records` or `contributors`.","type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"DatasetAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDatasetAttributes","description":"Attributes of a dataset.","type":"object","additionalProperties":false,"properties":{"dataSource":{"type":"string","description":"Who owns the dataset.\n- `fabric`: system-provisioned.\n- `custom`: tenant-created.","enum":["fabric","custom"]},"label":{"type":"string","description":"Display name."},"localized":{"type":"boolean","description":"When `true`, the dataset keys its items by locale."},"availableLocales":{"type":"array","description":"Locales a localized dataset supports.","items":{"type":"string"}},"key":{"type":"string","description":"Machine-readable identifier."},"tenantId":{"type":"string","description":"Tenant that owns the dataset."},"allowCustomItems":{"type":"boolean","description":"Whether tenants can add, update or delete items. When `false`, the dataset is locked and accepts no item changes."}},"required":["dataSource","label","key"]},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Timestamps on every resource's attributes, as ISO 8601 date-times. `created` marks the resource's creation; `updated` marks its last change.","type":"object","additionalProperties":false,"required":["created","updated"],"properties":{"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/datasets/{datasetId}":{"get":{"summary":"Get a dataset","operationId":"datasetFindOne","description":"Returns one dataset with attributes such as `label`, `key`, `localized` and `allowCustomItems`, plus a link to its items.","tags":["Datasets"],"parameters":[{"name":"datasetId","description":"The dataset to return.","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetDatasetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete a dataset and its items

> Deletes a dataset and all its items. Answers 409 while any field links to the dataset; unlink it from those fields first.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Datasets","description":"Manage a tenant's datasets. A dataset is an ordered list of items that limits a field's values, such as genres or ratings. Every tenant gets the shared system datasets and can add its own."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"WriteMetaOnlyRequest":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteMetaOnlyRequest","description":"An optional body with only audit metadata, for mutations that take no other body, such as deletes. Use it to send `meta.audit.source` and `meta.audit.reason`.","type":"object","additionalProperties":false,"properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"}}},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Audit metadata for a write request. `audit.source` names the surface that sent it, such as `studio-web`, `studio-mcp`, `api` or `system`; `audit.reason` is a free-text justification.","type":"object","additionalProperties":false,"properties":{"audit":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string","maxLength":64},"reason":{"type":"string","maxLength":256}}}}},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false}}},"paths":{"/datasets/{datasetId}":{"delete":{"summary":"Delete a dataset and its items","operationId":"datasetDeleteOne","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WriteMetaOnlyRequest"}}}},"description":"Deletes a dataset and all its items. Answers 409 while any field links to the dataset; unlink it from those fields first.","tags":["Datasets"],"parameters":[{"name":"datasetId","description":"The dataset to delete.","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict: a field still links to the dataset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update a dataset

> Updates the dataset's \`label\`. To add, change or remove items, use \`datasetAtomicOperations\`.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Datasets","description":"Manage a tenant's datasets. A dataset is an ordered list of items that limits a field's values, such as genres or ratings. Every tenant gets the shared system datasets and can add its own."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"PatchDatasetRequest":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IPatchDatasetRequest","description":"Updates a dataset. Changes only the attributes in `data.attributes`. `data.id` must match the `datasetId` path parameter.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"},"data":{"allOf":[{"$ref":"#/components/schemas/BaseResource"},{"required":["id","attributes"],"additionalProperties":false,"properties":{"attributes":{"type":"object","properties":{"label":{"type":"string"}},"additionalProperties":false}}}]}},"required":["data"],"additionalProperties":false},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Audit metadata for a write request. `audit.source` names the surface that sent it, such as `studio-web`, `studio-mcp`, `api` or `system`; `audit.reason` is a free-text justification.","type":"object","additionalProperties":false,"properties":{"audit":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string","maxLength":64},"reason":{"type":"string","maxLength":256}}}}},"BaseResource":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResource","description":"A resource identifier. Every resource object carries a unique `id` and a `type`, the resource type name such as `records` or `contributors`.","type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"GetDatasetResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IGetDatasetResponse","description":"One dataset, with its attributes, relationship links and a self link.","type":"object","required":["data","links","jsonapi"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/Dataset"},"links":{"type":"object","required":["self"],"properties":{"self":{"type":"string"}},"additionalProperties":false},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Dataset":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDataset","description":"A dataset: a controlled vocabulary or lookup list that constrains field values. A localized dataset keys its items by locale.","allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"attributes":{"allOf":[{"$ref":"#/components/schemas/DatasetAttributes"},{"$ref":"#/components/schemas/BaseResourceAttributes"}],"additionalProperties":false},"meta":{"type":"object","properties":{"tenantId":{"type":"string"},"allowCustomItems":{"type":"boolean","description":"Whether users can add, update or delete items. When `false`, the dataset is locked: users can't change items, and only Fabric manages them."}},"additionalProperties":false},"relationships":{"type":"object","properties":{"tenant":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"links":{"type":"object","properties":{"related":{"type":"string"}},"required":["related"],"additionalProperties":false}},"additionalProperties":false},"items":{"type":"object","properties":{"links":{"type":"object","properties":{"related":{"type":"string"}},"required":["related"],"additionalProperties":false}},"additionalProperties":false}},"required":["tenant"],"additionalProperties":false}},"required":["attributes","meta"],"additionalProperties":false}]},"DatasetAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDatasetAttributes","description":"Attributes of a dataset.","type":"object","additionalProperties":false,"properties":{"dataSource":{"type":"string","description":"Who owns the dataset.\n- `fabric`: system-provisioned.\n- `custom`: tenant-created.","enum":["fabric","custom"]},"label":{"type":"string","description":"Display name."},"localized":{"type":"boolean","description":"When `true`, the dataset keys its items by locale."},"availableLocales":{"type":"array","description":"Locales a localized dataset supports.","items":{"type":"string"}},"key":{"type":"string","description":"Machine-readable identifier."},"tenantId":{"type":"string","description":"Tenant that owns the dataset."},"allowCustomItems":{"type":"boolean","description":"Whether tenants can add, update or delete items. When `false`, the dataset is locked and accepts no item changes."}},"required":["dataSource","label","key"]},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Timestamps on every resource's attributes, as ISO 8601 date-times. `created` marks the resource's creation; `updated` marks its last change.","type":"object","additionalProperties":false,"required":["created","updated"],"properties":{"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/datasets/{datasetId}":{"patch":{"summary":"Update a dataset","operationId":"datasetUpdateOne","description":"Updates the dataset's `label`. To add, change or remove items, use `datasetAtomicOperations`.","tags":["Datasets"],"parameters":[{"name":"datasetId","description":"The dataset to update.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchDatasetRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetDatasetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a dataset's items

> Lists a dataset's items, such as individual genres or ratings.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Datasets","description":"Manage a tenant's datasets. A dataset is an ordered list of items that limits a field's values, such as genres or ratings. Every tenant gets the shared system datasets and can add its own."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"GetDatasetItemsResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IGetDatasetItemsResponse","description":"The items in a dataset, paginated. Each item carries `key`, `value` and `locale` attributes and relationship links to its dataset.","type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DatasetItem"},"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"}},"additionalProperties":false},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}},"required":["data","links","jsonapi"],"additionalProperties":false},"DatasetItem":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDatasetItem","description":"One entry in a dataset: a `key`, a display `value`, and a `locale` in localized datasets.","allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"attributes":{"allOf":[{"$ref":"#/components/schemas/DatasetItemAttributes"},{"$ref":"#/components/schemas/BaseResourceAttributes"}],"additionalProperties":false},"relationships":{"type":"object","properties":{"dataset":{"$ref":"#/components/schemas/DatasetRelationship"},"tenant":{"$ref":"#/components/schemas/TenantRelationship"}},"additionalProperties":false}},"required":["attributes","relationships"],"additionalProperties":false}]},"BaseResource":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResource","description":"A resource identifier. Every resource object carries a unique `id` and a `type`, the resource type name such as `records` or `contributors`.","type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"DatasetItemAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDatasetItemAttributes","description":"Attributes of one dataset item.","type":"object","additionalProperties":false,"properties":{"locale":{"type":"string","description":"Language and region the item belongs to, in a localized dataset."},"dataSource":{"type":"string","description":"Who created the item: Fabric or the tenant."},"key":{"type":"string","description":"Stable machine-readable identifier. Records store this key."},"value":{"type":"string","description":"Display label the UI shows."}},"required":["key","value"]},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Timestamps on every resource's attributes, as ISO 8601 date-times. `created` marks the resource's creation; `updated` marks its last change.","type":"object","additionalProperties":false,"required":["created","updated"],"properties":{"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"DatasetRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IDatasetRelationship","description":"Links a resource to a dataset. `links.related` fetches the full dataset.","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["datasets"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data","links"],"additionalProperties":false},"LinksRelated":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ILinks","description":"A JSON:API links object with an absolute or relative 'related' link","type":"object","required":["related"],"properties":{"related":{"type":"string"}},"additionalProperties":false},"TenantRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ITenantRelationship","description":"A relationship to a tenant","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["tenants"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data","links"],"additionalProperties":false},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/datasets/{datasetId}/items":{"get":{"summary":"Get a dataset's items","operationId":"datasetItemFindMany","description":"Lists a dataset's items, such as individual genres or ratings.","tags":["Datasets"],"parameters":[{"name":"datasetId","description":"The dataset whose items to list.","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter.locale","description":"Only items in this locale. Defaults to `default`, where non-localized datasets keep their items.","in":"query","schema":{"type":"string"},"required":false},{"name":"filter.searchTerm","in":"query","required":false,"style":"form","explode":false,"schema":{"type":"string"},"description":"Text search within the items."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetDatasetItemsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Change a dataset's items

> Applies up to 99 item operations in one all-or-nothing write. Works only on datasets with \`allowCustomItems: true\`.\
> \- \`add\`: creates an item.\
> \- \`update\`: changes an item's display value.\
> \- \`remove\`: deletes an item.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Datasets","description":"Manage a tenant's datasets. A dataset is an ordered list of items that limits a field's values, such as genres or ratings. Every tenant gets the shared system datasets and can add its own."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"ExecuteDatasetOperationRequest":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IExecuteDatasetOperationRequest","description":"Adds, updates and removes dataset items in one all-or-nothing request (JSON:API Atomic Operations).\n- At most 99 operations per request.\n- One item can't appear in conflicting operations, such as both `add` and `remove`.\n- Only datasets with `allowCustomItems: true` accept item changes.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"},"atomic:operations":{"type":"array","items":{"$ref":"#/components/schemas/ExecuteDatasetOperationRequestData"}}},"required":["atomic:operations"],"additionalProperties":false},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Audit metadata for a write request. `audit.source` names the surface that sent it, such as `studio-web`, `studio-mcp`, `api` or `system`; `audit.reason` is a free-text justification.","type":"object","additionalProperties":false,"properties":{"audit":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string","maxLength":64},"reason":{"type":"string","maxLength":256}}}}},"ExecuteDatasetOperationRequestData":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IExecuteDatasetOperationRequestData","description":"One operation.\n- `op`: `add`, `update` or `remove`.\n- `ref`: the target item, for `update` and `remove`.\n- `data`: the item payload, for `add` and `update`.","type":"object","properties":{"op":{"type":"string","enum":["add","remove","update"]},"ref":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"relationship":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"data":{"anyOf":[{"$ref":"#/components/schemas/AddDatasetItemOperation"},{"$ref":"#/components/schemas/UpdateDatasetItemOperation"}]}},"required":["op","ref"],"additionalProperties":false},"AddDatasetItemOperation":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IAddDatasetItemOperation","description":"The new dataset item for an `add` operation: `key`, `value` and an optional `locale`.","type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"key":{"type":"string","description":"Machine-readable identifier that records store when they reference the item. 2 to 50 letters, digits, underscores and hyphens, starting with a letter or digit.","minLength":2,"maxLength":50},"value":{"type":"string"},"locale":{"type":"string"}},"required":["key","value"],"additionalProperties":false}},"required":["type","attributes"],"additionalProperties":false},"UpdateDatasetItemOperation":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUpdateDatasetItemOperation","description":"Payload of an `update` operation on a dataset item: the item's id and type, and the new `value`.","type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"value":{"type":"string"}},"required":["value"],"additionalProperties":false}},"required":["type","attributes"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false}}},"paths":{"/datasets/{datasetId}/operations":{"post":{"summary":"Change a dataset's items","operationId":"datasetAtomicOperations","description":"Applies up to 99 item operations in one all-or-nothing write. Works only on datasets with `allowCustomItems: true`.\n- `add`: creates an item.\n- `update`: changes an item's display value.\n- `remove`: deletes an item.","tags":["Datasets"],"parameters":[{"name":"datasetId","description":"The dataset to change.","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteDatasetOperationRequest"}}},"required":true},"responses":{"204":{"description":"No Content"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
