> For the complete documentation index, see [llms.txt](https://docs.truedat.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.truedat.io/v8.12/api-integrations/data-catalog-data-lineage-and-grants-apis/data-structure-filters.md).
# Data Structure Filters
## List data structure filters
> Returns the available data-structure filter buckets for the current request context.\
> \
> Uses the active \`search\_permission\` from the request. The response is permission-aware and varies by the caller's visibility and the active permission scope.
```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.12.2"},"paths":{"/api/data_structure_filters":{"get":{"description":"Returns the available data-structure filter buckets for the current request context.\n\nUses the active `search_permission` from the request. The response is permission-aware and varies by the caller's visibility and the active permission scope.\n","operationId":"TdDdWeb.DataStructureFilterController.index","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStructureFiltersResponse"}}},"description":"Data structure filters"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"List data structure filters","tags":["Data Structure Filters"]}}},"components":{"schemas":{"DataStructureFiltersResponse":{"properties":{"data":{"additionalProperties":true,"type":"object"}},"title":"DataStructureFiltersResponse","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```
## Get bucket paths
> Retrieves hierarchical bucket paths for the supplied filter payload.\
> \
> Uses the request's active search permission.\
> \
> The response is designed for UI expansion of hierarchical filters and includes the nested path structure plus the filtered child information used by the client.
```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.12.2"},"paths":{"/api/buckets/paths":{"post":{"description":"Retrieves hierarchical bucket paths for the supplied filter payload.\n\nUses the request's active search permission.\n\nThe response is designed for UI expansion of hierarchical filters and includes the nested path structure plus the filtered child information used by the client.\n","operationId":"TdDdWeb.DataStructureFilterController.get_bucket_paths","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BucketPathsRequest"}}},"description":"Bucket paths payload","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BucketPathsResponse"}}},"description":"Bucket paths response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Get bucket paths","tags":["Data Structure Filters"]}}},"components":{"schemas":{"BucketPathsRequest":{"additionalProperties":true,"properties":{"bucket":{"description":"Bucket name","type":"string"},"prefix":{"description":"Prefix to filter paths","type":"string"}},"title":"BucketPathsRequest","type":"object"},"BucketPathsResponse":{"properties":{"filtered_children":{"additionalProperties":{"items":{"type":"integer"},"type":"array"},"description":"Map of parent ID to list of child IDs that have filtered descendants","type":"object"},"forest":{"additionalProperties":{"additionalProperties":true,"type":"object"},"description":"Hierarchical tree of data structure IDs","type":"object"}},"required":["forest","filtered_children"],"title":"BucketPathsResponse","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```
## Search data structure filters
> Searches data-structure filter values using the supplied payload and the caller's permission context.\
> \
> \*\*Permission overrides:\*\*\
> \- \`my\_grant\_requests = true\` evaluates filter visibility in the \*\*'Create grant request'\*\* permission context.\
> \- \`link\_structures = true\` evaluates filter visibility in the \*\*'Link structures'\*\* permission context.\
> \- Otherwise, the endpoint uses the default search permission already assigned to the request.\
> \
> \*\*Other request values allowed:\*\* \`query\`, \`filters\`, \`page\` and \`size\` (optional), \`scroll\` and \`scroll\_id\` for scroll-based pagination
```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.12.2"},"paths":{"/api/data_structure_filters/search":{"post":{"description":"Searches data-structure filter values using the supplied payload and the caller's permission context.\n\n**Permission overrides:**\n- `my_grant_requests = true` evaluates filter visibility in the **'Create grant request'** permission context.\n- `link_structures = true` evaluates filter visibility in the **'Link structures'** permission context.\n- Otherwise, the endpoint uses the default search permission already assigned to the request.\n\n**Other request values allowed:** `query`, `filters`, `page` and `size` (optional), `scroll` and `scroll_id` for scroll-based pagination\n","operationId":"TdDdWeb.DataStructureFilterController.search","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStructureFilterSearchRequest"}}},"description":"Filter search payload","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStructureFiltersResponse"}}},"description":"Filtered results"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Search data structure filters","tags":["Data Structure Filters"]}}},"components":{"schemas":{"DataStructureFilterSearchRequest":{"additionalProperties":true,"description":"Filter search payload used to compute permission-aware aggregation values for data structures. The request can run against the default search permission or override it with either `my_grant_requests` or `link_structures` to adapt the permission context. Common values include `query`, `filters`, `page` (default `0`), `size` (default `50`), `scroll`, and `scroll_id`.","properties":{"filters":{"additionalProperties":true,"description":"Exact filter criteria to apply before reading the aggregation buckets.","type":"object"},"link_structures":{"default":false,"description":"If true, computes filter values for structures that the current user can link.","type":"boolean"},"my_grant_requests":{"default":false,"description":"If true, computes filter values in the grant-request context for the current user.","type":"boolean"},"page":{"default":0,"description":"Page number for pagination.","minimum":0,"type":"integer"},"query":{"description":"Full-text search query used to narrow the filter candidates.","type":"string"},"scroll":{"description":"Scroll timeout value, for example `1m`.","type":"string"},"scroll_id":{"description":"Scroll ID for retrieving the next section of results.","type":"string"},"size":{"default":50,"description":"Page size for paginated results.","minimum":1,"type":"integer"}},"title":"DataStructureFilterSearchRequest","type":"object"},"DataStructureFiltersResponse":{"properties":{"data":{"additionalProperties":true,"type":"object"}},"title":"DataStructureFiltersResponse","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```