> 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/suggestions.md).

# Suggestions

## Search data structure suggestions

> Returns suggested data structures based on a query or a reference resource.\
> \
> Requires the \*\*'View structures'\*\* permission on at least one domain. Additionally, the suggestions feature must be enabled in the system.\
> \
> \*\*Request body:\*\*\
> \- \`resource\` (optional, object) – A reference resource to get suggestions for. Must contain:\
>   \- \`type\` (required, string) – Resource type (e.g., 'concepts').\
>   \- \`id\` (required, integer) – Resource ID.\
>   \- \`version\` (optional, integer) – Resource version.\
>   \- \`links\` (optional, array) – Additional links.\
> \- \`query\` (optional, string) – Free‑text search query to find similar structures.\
> \- \`size\` (optional, integer) – Maximum number of suggestions to return. Default: \*\*10\*\*.\
> \
> At least one of \`resource\` or \`query\` must be provided. The endpoint uses the active search permission from the request context to filter results. The response contains the suggested data structures in the same format as the search endpoint.\
> \
> The suggestions are generated using a k‑nearest‑neighbors (kNN) algorithm over the suggestions index. If the index is not enabled, the endpoint will not return results.<br>

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.12.2"},"paths":{"/api/data_structures/suggestions":{"post":{"description":"Returns suggested data structures based on a query or a reference resource.\n\nRequires the **'View structures'** permission on at least one domain. Additionally, the suggestions feature must be enabled in the system.\n\n**Request body:**\n- `resource` (optional, object) – A reference resource to get suggestions for. Must contain:\n  - `type` (required, string) – Resource type (e.g., 'concepts').\n  - `id` (required, integer) – Resource ID.\n  - `version` (optional, integer) – Resource version.\n  - `links` (optional, array) – Additional links.\n- `query` (optional, string) – Free‑text search query to find similar structures.\n- `size` (optional, integer) – Maximum number of suggestions to return. Default: **10**.\n\nAt least one of `resource` or `query` must be provided. The endpoint uses the active search permission from the request context to filter results. The response contains the suggested data structures in the same format as the search endpoint.\n\nThe suggestions are generated using a k‑nearest‑neighbors (kNN) algorithm over the suggestions index. If the index is not enabled, the endpoint will not return results.\n","operationId":"TdDdWeb.SuggestionController.search","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStructureSuggestionsRequest"}}},"description":"Suggestion filters","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStructureSearchResponse"}}},"description":"Data structure suggestions"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Search data structure suggestions","tags":["Suggestions"]}}},"components":{"schemas":{"DataStructureSuggestionsRequest":{"additionalProperties":true,"properties":{"query":{"description":"Search query text","nullable":true,"type":"string"},"resource":{"additionalProperties":false,"description":"Resource to get suggestions for","properties":{"id":{"description":"Resource ID","type":"integer"},"links":{"items":{"additionalProperties":true,"type":"object"},"nullable":true,"type":"array"},"type":{"description":"Resource type (e.g., 'concepts')","type":"string"},"version":{"description":"Resource version","nullable":true,"type":"integer"}},"required":["type","id"],"type":"object"},"size":{"default":10,"description":"Number of suggestions to return","minimum":1,"nullable":true,"type":"integer"}},"title":"DataStructureSuggestionsRequest","type":"object"},"DataStructureSearchResponse":{"additionalProperties":false,"properties":{"_actions":{"additionalProperties":true,"nullable":true,"type":"object"},"data":{"items":{"$ref":"#/components/schemas/DataStructure"},"type":"array"},"filters":{"additionalProperties":true,"type":"object"},"scroll_id":{"nullable":true,"type":"string"}},"required":["data"],"title":"DataStructureSearchResponse","type":"object"},"DataStructure":{"additionalProperties":false,"properties":{"my_grant_request":{"nullable":true,"type":"object"},"siblings":{"items":{"$ref":"#/components/schemas/DataStructure"},"nullable":true,"type":"array"},"inserted_at":{"format":"date-time","type":"string"},"note_last_changed_by":{"nullable":true,"type":"string"},"links":{"items":{"type":"object"},"nullable":true,"type":"array"},"type":{"type":"string"},"domains":{"items":{"$ref":"#/components/schemas/Domain"},"nullable":true,"type":"array"},"my_grants":{"items":{"$ref":"#/components/schemas/DataStructure"},"nullable":true,"type":"array"},"path":{"items":{"type":"string"},"nullable":true,"type":"array"},"note_last_changed_at":{"format":"date-time","nullable":true,"type":"string"},"parent_id":{"nullable":true,"type":"string"},"class":{"nullable":true,"type":"string"},"versions":{"items":{"$ref":"#/components/schemas/DataStructureVersion"},"nullable":true,"type":"array"},"source":{"additionalProperties":true,"nullable":true,"type":"object"},"original_name":{"nullable":true,"type":"string"},"deleted_at":{"format":"date-time","nullable":true,"type":"string"},"source_id":{"nullable":true,"type":"integer"},"children":{"items":{"$ref":"#/components/schemas/DataStructure"},"nullable":true,"type":"array"},"note":{"additionalProperties":true,"nullable":true,"type":"object"},"updated_at":{"format":"date-time","type":"string"},"description":{"nullable":true,"type":"string"},"name":{"type":"string"},"id":{"type":"integer"},"user_permissions":{"$ref":"#/components/schemas/UserPermissions"},"field_type":{"nullable":true,"type":"string"},"system_id":{"nullable":true,"type":"integer"},"classes":{"additionalProperties":true,"nullable":true,"type":"object"},"metadata_versions":{"items":{"type":"object"},"nullable":true,"type":"array"},"external_id":{"nullable":true,"type":"string"},"system":{"$ref":"#/components/schemas/System"},"ancestry":{"items":{"type":"object"},"nullable":true,"type":"array"},"parents":{"items":{"$ref":"#/components/schemas/DataStructure"},"nullable":true,"type":"array"},"domain_ids":{"items":{"type":"integer"},"nullable":true,"type":"array"},"linked_concepts":{"nullable":true,"type":"boolean"},"group":{"nullable":true,"type":"string"},"domain":{"additionalProperties":true,"nullable":true,"type":"object"},"confidential":{"nullable":true,"type":"boolean"},"metadata":{"additionalProperties":true,"nullable":true,"type":"object"},"non_published_note":{"additionalProperties":true,"nullable":true,"type":"object"},"data_fields":{"items":{"type":"object"},"nullable":true,"type":"array"},"last_change_at":{"format":"date-time","nullable":true,"type":"string"},"version":{"nullable":true,"type":"integer"},"relations":{"additionalProperties":true,"nullable":true,"type":"object"}},"required":["id","name","type","system"],"title":"DataStructure","type":"object"},"Domain":{"additionalProperties":false,"properties":{"external_id":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"parent_id":{"nullable":true,"type":"integer"},"parents":{"items":{"additionalProperties":false,"properties":{"external_id":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}},"type":"object"},"nullable":true,"type":"array"},"updated_at":{"nullable":true,"type":"string"}},"required":["id","external_id","name"],"title":"Domain","type":"object"},"DataStructureVersion":{"additionalProperties":false,"properties":{"_actions":{"additionalProperties":true,"nullable":true,"type":"object"},"children":{"items":{"$ref":"#/components/schemas/DataStructureVersion"},"nullable":true,"type":"array"},"class":{"nullable":true,"type":"string"},"classes":{"additionalProperties":{"type":"string"},"nullable":true,"type":"object"},"data_fields":{"items":{"additionalProperties":true,"type":"object"},"nullable":true,"type":"array"},"data_structure":{"additionalProperties":false,"properties":{"deleted_at":{"format":"date-time","nullable":true,"type":"string"},"domains":{"items":{"$ref":"#/components/schemas/Domain"},"nullable":true,"type":"array"},"external_id":{"type":"string"},"id":{"type":"integer"}},"type":"object"},"deleted_at":{"format":"date-time","nullable":true,"type":"string"},"domains":{"items":{"$ref":"#/components/schemas/Domain"},"nullable":true,"type":"array"},"external_id":{"nullable":true,"type":"string"},"grant":{"$ref":"#/components/schemas/DataStructure"},"grants":{"items":{"$ref":"#/components/schemas/DataStructure"},"nullable":true,"type":"array"},"group":{"nullable":true,"type":"string"},"implementation_count":{"nullable":true,"type":"integer"},"inserted_at":{"format":"date-time","type":"string"},"metadata":{"additionalProperties":true,"type":"object"},"name":{"nullable":true,"type":"string"},"note":{"$ref":"#/components/schemas/Note"},"parents":{"items":{"$ref":"#/components/schemas/DataStructureVersion"},"nullable":true,"type":"array"},"siblings":{"items":{"$ref":"#/components/schemas/DataStructureVersion"},"nullable":true,"type":"array"},"system":{"$ref":"#/components/schemas/System"},"type":{"nullable":true,"type":"string"},"updated_at":{"format":"date-time","type":"string"},"user_permissions":{"$ref":"#/components/schemas/UserPermissions"},"version":{"type":"integer"}},"required":["version"],"title":"DataStructureVersion","type":"object"},"Note":{"additionalProperties":true,"description":"Dynamic content of the published note","title":"Note","type":"object"},"System":{"additionalProperties":false,"properties":{"external_id":{"nullable":true,"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"],"title":"System","type":"object"},"UserPermissions":{"additionalProperties":true,"properties":{"confidential":{"type":"boolean"},"profile_permission":{"type":"boolean"},"request_grant":{"type":"boolean"},"update":{"type":"boolean"},"update_grant_removal":{"type":"boolean"},"view_lineage":{"type":"boolean"},"view_profiling_permission":{"type":"boolean"}},"title":"UserPermissions","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"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```