--- title: "Search" method: GET path: "/api/entities/search" tags: ["Entities"] --- # Search `GET /api/entities/search` ## Request - Base URL: `https://app.polytomic.com` - URL: `https://app.polytomic.com/api/entities/search` - Auth: one of: - HTTP bearer - HTTP basic Searches models, model fields, model syncs, bulk syncs, and connections in the caller's organization. Supply a nonblank `search` term to search all five result categories. Unlike [entity lookup](../../../api-reference/entities/get), this endpoint does not search Organizations, users, executions, Harbors, or Harbor contexts. Model fields are searchable but have no standalone lookup endpoint. ## Searchable resources - Models: ID, name, and source Connection type. - Model fields: ID, technical name, and label. - Model Syncs: ID, name, source and target Connection types, and saved field and identity mappings. Mappings include source field names and labels, target field IDs, and available target field names. - Bulk Syncs: ID, name, source and target Connection names and types, and enabled schema IDs, display names, and configured output names. Disabled schemas are excluded; enabled schemas remain searchable when the sync is inactive. - Connections: ID and name. Search uses cached metadata and does not refresh schemas. Names absent from that metadata are not searchable. Bulk Sync fields, execution state, expressions, filters, and constant values are not searched. ## Matching and evidence Matching is case-insensitive and uses word prefixes, not fuzzy matching. Every query word must match somewhere within a result. Spaces and punctuation split words: `other emails` matches `other_emails`, but `mail` does not match `email`. Some Model Sync source-type matches require a leading `~`. Each resource appears once. Its `matches` explain which attributes matched and which query terms contributed. Mapping and schema attributes carry their respective `mapping` or `schema` context; resource metadata has neither. A name or Connection type match alone does not establish mapping or schema use. Results include canonical `links`, not complete configurations or schema lists. ## Limits and completeness Results are ordered by category, then name or field label, then ID, not by relevance. `limit` defaults to 50 and accepts 1–100. It limits resource hits, not match evidence. When `metadata.truncated` is `true`, narrow your search or increase the limit. There is no cursor pagination. > ⚠️ Incomplete model-field coverage > > Above 40,000 published model fields, `metadata.model_fields_complete` is > `false`: standalone field results cover a subset, not every published field. > Model Sync mapping search is unaffected. Incomplete or truncated results > cannot establish that no other matches exist. ## Query parameters - `search` string, required: Search term matched, by word prefix, against models, model fields, model syncs, bulk syncs, and connections in the caller's organization - `limit` integer, nullable: Maximum number of results to return across all result types. Defaults to 50 and cannot exceed 100. ## Headers - `X-Polytomic-Version` string ## Response `200` OK - SearchEnvelope - `data` SearchResultItem[], nullable: Matching resources, ordered by type and name - union - ModelSearchHit - `links` SearchResultLinks, required - `bulk_sync` string: API path of the bulk sync - `connection` string: API path of the connection - `model` string: API path of the model - `model_sync` string: API path of the model sync - `source_connection` string: API path of the source connection - `target_connection` string: API path of the target connection - `matches` SearchMatch[], nullable, required: Contributing attributes grouped by saved mapping context, with one group for resource metadata - `attributes` SearchMatchAttribute[], nullable, required: Indexed attributes contributing to this result, with matching query terms - `attribute` string, required: Indexed attribute that matched a query term - `terms` string[], nullable, required: Unique normalized query terms matching word prefixes in this value - `value` string, required: Original indexed string, before tokenization and case normalization - `mapping` SearchMatchMapping - `kind` 'field' | 'primary_identity' | 'secondary_identity', required: Kind of saved mapping - `source_field_id` string, uuid: Field ID of the mapped source field - `source_field_label` string: Label of the mapped source field - `source_field_name` string: Source name of the mapped source field - `source_model_id` string, uuid: Model ID of the mapped source field - `source_model_name` string: Name of the model that owns the mapped source field - `target_field_id` string, required: Target field ID the source field maps to - `target_field_name` string: Target field name from stored schema metadata, when available - `schema` SearchMatchSchema - `output_name` string: Configured destination output name, when available - `schema_id` string, required: Saved source schema ID - `schema_name` string: Source schema display name from stored metadata, when available - `model_connection_id` string, uuid, required: Connection ID of the model - `model_connection_name` string, required: Name of the model's connection - `model_connection_type` string, required: Connection type of the model's connection - `model_id` string, uuid, required: Model ID - `model_name` string, required: Model name - `type` 'model', required: Result type - ModelFieldSearchHit - `field_id` string, uuid, required: Model field ID - `field_label` string, required: Model field label - `field_name` string, required: Source or technical field name - `links` SearchResultLinks, required - `bulk_sync` string: API path of the bulk sync - `connection` string: API path of the connection - `model` string: API path of the model - `model_sync` string: API path of the model sync - `source_connection` string: API path of the source connection - `target_connection` string: API path of the target connection - `matches` SearchMatch[], nullable, required: Contributing attributes grouped by saved mapping context, with one group for resource metadata - `attributes` SearchMatchAttribute[], nullable, required: Indexed attributes contributing to this result, with matching query terms - `attribute` string, required: Indexed attribute that matched a query term - `terms` string[], nullable, required: Unique normalized query terms matching word prefixes in this value - `value` string, required: Original indexed string, before tokenization and case normalization - `mapping` SearchMatchMapping - `kind` 'field' | 'primary_identity' | 'secondary_identity', required: Kind of saved mapping - `source_field_id` string, uuid: Field ID of the mapped source field - `source_field_label` string: Label of the mapped source field - `source_field_name` string: Source name of the mapped source field - `source_model_id` string, uuid: Model ID of the mapped source field - `source_model_name` string: Name of the model that owns the mapped source field - `target_field_id` string, required: Target field ID the source field maps to - `target_field_name` string: Target field name from stored schema metadata, when available - `schema` SearchMatchSchema - `output_name` string: Configured destination output name, when available - `schema_id` string, required: Saved source schema ID - `schema_name` string: Source schema display name from stored metadata, when available - `model_connection_id` string, uuid, required: Connection ID of the field's model - `model_connection_name` string, required: Name of the connection of the field's model - `model_connection_type` string, required: Connection type of the connection of the field's model - `model_id` string, uuid, required: Model ID of the field's model - `model_name` string, required: Name of the field's model - `type` 'model_field', required: Result type - ModelSyncSearchHit - `links` SearchResultLinks, required - `bulk_sync` string: API path of the bulk sync - `connection` string: API path of the connection - `model` string: API path of the model - `model_sync` string: API path of the model sync - `source_connection` string: API path of the source connection - `target_connection` string: API path of the target connection - `matches` SearchMatch[], nullable, required: Contributing attributes grouped by saved mapping context, with one group for resource metadata - `attributes` SearchMatchAttribute[], nullable, required: Indexed attributes contributing to this result, with matching query terms - `attribute` string, required: Indexed attribute that matched a query term - `terms` string[], nullable, required: Unique normalized query terms matching word prefixes in this value - `value` string, required: Original indexed string, before tokenization and case normalization - `mapping` SearchMatchMapping - `kind` 'field' | 'primary_identity' | 'secondary_identity', required: Kind of saved mapping - `source_field_id` string, uuid: Field ID of the mapped source field - `source_field_label` string: Label of the mapped source field - `source_field_name` string: Source name of the mapped source field - `source_model_id` string, uuid: Model ID of the mapped source field - `source_model_name` string: Name of the model that owns the mapped source field - `target_field_id` string, required: Target field ID the source field maps to - `target_field_name` string: Target field name from stored schema metadata, when available - `schema` SearchMatchSchema - `output_name` string: Configured destination output name, when available - `schema_id` string, required: Saved source schema ID - `schema_name` string: Source schema display name from stored metadata, when available - `source_connections` ModelSyncSourceConnection[], required: Connections of the models this sync maps from - `connection_id` string, uuid, required: Source connection ID - `connection_name` string, required: Source connection name - `connection_type` string, required: Source connection type - `sync_id` string, uuid, required: Model sync ID - `sync_name` string, required: Model sync name - `target_connection_id` string, uuid, required: Target connection ID - `target_connection_name` string, required: Target connection name - `target_connection_type` string, required: Target connection type - `type` 'model_sync', required: Result type - BulkSyncSearchHit - `bulk_sync_id` string, uuid, required: Bulk sync ID - `bulk_sync_name` string, required: Bulk sync name - `links` SearchResultLinks, required - `bulk_sync` string: API path of the bulk sync - `connection` string: API path of the connection - `model` string: API path of the model - `model_sync` string: API path of the model sync - `source_connection` string: API path of the source connection - `target_connection` string: API path of the target connection - `matches` SearchMatch[], nullable, required: Contributing attributes grouped by saved mapping or schema context, with one group for resource metadata - `attributes` SearchMatchAttribute[], nullable, required: Indexed attributes contributing to this result, with matching query terms - `attribute` string, required: Indexed attribute that matched a query term - `terms` string[], nullable, required: Unique normalized query terms matching word prefixes in this value - `value` string, required: Original indexed string, before tokenization and case normalization - `mapping` SearchMatchMapping - `kind` 'field' | 'primary_identity' | 'secondary_identity', required: Kind of saved mapping - `source_field_id` string, uuid: Field ID of the mapped source field - `source_field_label` string: Label of the mapped source field - `source_field_name` string: Source name of the mapped source field - `source_model_id` string, uuid: Model ID of the mapped source field - `source_model_name` string: Name of the model that owns the mapped source field - `target_field_id` string, required: Target field ID the source field maps to - `target_field_name` string: Target field name from stored schema metadata, when available - `schema` SearchMatchSchema - `output_name` string: Configured destination output name, when available - `schema_id` string, required: Saved source schema ID - `schema_name` string: Source schema display name from stored metadata, when available - `source_connection_id` string, uuid, required: Source connection ID - `source_connection_name` string, required: Source connection name - `source_connection_type` string, required: Source connection type - `target_connection_id` string, uuid, required: Target connection ID - `target_connection_name` string, required: Target connection name - `target_connection_type` string, required: Target connection type - `type` 'bulk_sync', required: Result type - ConnectionSearchHit - `connection_id` string, uuid, required: Connection ID - `connection_name` string, required: Connection name - `connection_type` string, required: Connection type - `links` SearchResultLinks, required - `bulk_sync` string: API path of the bulk sync - `connection` string: API path of the connection - `model` string: API path of the model - `model_sync` string: API path of the model sync - `source_connection` string: API path of the source connection - `target_connection` string: API path of the target connection - `matches` SearchMatch[], nullable, required: Contributing attributes grouped by saved mapping context, with one group for resource metadata - `attributes` SearchMatchAttribute[], nullable, required: Indexed attributes contributing to this result, with matching query terms - `attribute` string, required: Indexed attribute that matched a query term - `terms` string[], nullable, required: Unique normalized query terms matching word prefixes in this value - `value` string, required: Original indexed string, before tokenization and case normalization - `mapping` SearchMatchMapping - `kind` 'field' | 'primary_identity' | 'secondary_identity', required: Kind of saved mapping - `source_field_id` string, uuid: Field ID of the mapped source field - `source_field_label` string: Label of the mapped source field - `source_field_name` string: Source name of the mapped source field - `source_model_id` string, uuid: Model ID of the mapped source field - `source_model_name` string: Name of the model that owns the mapped source field - `target_field_id` string, required: Target field ID the source field maps to - `target_field_name` string: Target field name from stored schema metadata, when available - `schema` SearchMatchSchema - `output_name` string: Configured destination output name, when available - `schema_id` string, required: Saved source schema ID - `schema_name` string: Source schema display name from stored metadata, when available - `type` 'connection', required: Result type - `metadata` SearchResultMetadata - `model_fields_complete` boolean: False when the organization's published model-field count exceeds the hydration threshold (40,000). In that case model_field results cover a used-fields subset (unique fields and sync or relationship references), plus enrichment fields, rather than every published field. This flag does not limit saved Model Sync mapping search. - `truncated` boolean: True when more matches exist than were returned. Narrow the search term or increase limit (up to its maximum) to see more. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `500`: Internal Server Error ## Changes - **2026-10-22** `d80b0fdea14e`: 6 breaking, 32 warning, 6 info - the `data/items/oneOf[subschema #1: ModelSearchHit]/links` response's property type changed from `object` to no type for status `200` - the `data/items/oneOf[subschema #2: ModelFieldSearchHit]/links` response's property type changed from `object` to no type for status `200` - the `data/items/oneOf[subschema #3: ModelSyncSearchHit]/links` response's property type changed from `object` to no type for status `200` - the `data/items/oneOf[subschema #4: BulkSyncSearchHit]/links` response's property type changed from `object` to no type for status `200` - …40 more - **2026-10-21** `61c2b96f65ba`: 25 breaking, 40 warning, 10 info - the `data/items/oneOf[subschema #1: ModelSearchHit]/matches/items/mapping` response's property type changed from `object` to no type for status `200` - the `data/items/oneOf[subschema #1: ModelSearchHit]/matches/items/schema` response's property type changed from `object` to no type for status `200` - the `data/items/oneOf[subschema #2: ModelFieldSearchHit]/matches/items/mapping` response's property type changed from `object` to no type for status `200` - the `data/items/oneOf[subschema #2: ModelFieldSearchHit]/matches/items/schema` response's property type changed from `object` to no type for status `200` - …71 more - **2026-10-07** `dbe29f9bc9cc`: 1 info - endpoint added [Operation history](https://skmtc.dev/polytomic/apis/polytomic-api/changes/api/entities/search/get.md) --- [API](https://skmtc.dev/polytomic/apis/polytomic-api.md) - [All operations](https://skmtc.dev/polytomic/apis/polytomic-api/llms.txt) - [OpenAPI document](https://skmtc.dev/polytomic/apis/polytomic-api/revisions/3c88180d2470?raw)