--- title: "Search" method: GET path: "/v3/api/search" tags: ["search"] --- # Search `GET /v3/api/search` ## Request - Base URL: `https://monarchinitiative.org` (the document declares no server; this is the origin it was published from) - URL: `https://monarchinitiative.org/v3/api/search` - Auth: none declared Search for entities by label, with optional filters Args: q (str, optional): Query string. Defaults to "*:*". category (str, optional): Filter by biolink model category. Defaults to None. in_taxon (str, optional): Filter by taxon CURIE. Defaults to None. in_taxon_label (str, optional): Filter by taxon label. Defaults to None. namespace (str, optional): Restrict to these CURIE namespaces. Defaults to None. exclude_namespace (str, optional): Drop these CURIE namespaces. Defaults to None. subset (str, optional): Restrict to entities in these ontology subsets. Defaults to None. exclude_subset (str, optional): Drop entities in these ontology subsets. Defaults to None. scope (SearchScope, optional): A named filter bundle. Supplies category, namespace, subset, exclude_subset and in_taxon where they were not passed explicitly; an explicit value wins for that axis. The resolved filters are echoed on the response. Defaults to None. facets (bool, optional): `True` facets every filterable field with no cap on values, which is how a caller discovers what `namespace` and `subsets` accept. `False` disables faceting. Omitted keeps the historical category + in_taxon_label counts. Defaults to None. match_type (SearchMatchType, optional): `relevance` (default) or `exact`. In `exact` mode a result is returned only when `q` equals the entity's name or one of its exact synonyms as a whole string, case-insensitively; otherwise the result set is empty. Items carry `matched_field` and `match_type` so callers can apply their own precision policy. Defaults to `relevance`. include_phenotypes (bool, optional): Include phenotype annotations and closures. Defaults to False. include_descendants (bool, optional): Include ontology descendants. Defaults to False. offset (int, optional): Offset for pagination. Defaults to 0. limit (int, optional): Limit results. Defaults to 20. Returns: EntityResults ## Query parameters - `q` string - `category` EntityCategory[], nullable - `in_taxon` string[], nullable - `in_taxon_label` string[], nullable - `namespace` string[], nullable - `exclude_namespace` string[], nullable - `subset` string[], nullable - `exclude_subset` string[], nullable - `scope` 'human_disease' | 'human_phenotype' | 'human_gene' | 'rare_disease': The named filter bundles `/search?scope=` accepts. - `facets` boolean, nullable - `match_type` 'relevance' | 'exact': How strict `/search` should be about what counts as a hit. `relevance` is the search contract: maximise recall and always return the best available hit. `exact` is the grounding contract: return an entity only when the query names it, and an empty result set otherwise. - `include_phenotypes` boolean: Include the entity's phenotype annotations and their closures. Large: these are most of the response when present. - `include_descendants` boolean: Include the entity's ontology descendants. Large: these are most of the response when present. - `limit` integer - `offset` integer ## Response `200` Successful Response - SearchResults - `limit` integer, required: number of items to return in a response - `offset` integer, required: offset into the total number of items - `total` integer, required: total number of items matching a query - `items` SearchResult[], required: A collection of items, with the type to be overriden by slot_usage - `id` string, required - `category` string, required - `name` string, required - `description` string, nullable - `xref` string[], nullable - `synonym` string[], nullable - `exact_synonym` string[], nullable: An exact synonym for the entity - `broad_synonym` string[], nullable: A broader synonym for the entity - `narrow_synonym` string[], nullable: A narrower synonym for the entity - `related_synonym` string[], nullable: A related synonym for the entity - `deprecated` boolean, nullable: A boolean flag indicating that an entity is no longer considered current or valid. - `in_taxon` string, nullable: The biolink taxon that the entity is in the closure of. - `in_taxon_label` string, nullable: The label of the biolink taxon that the entity is in the closure of. - `iri` string, nullable - `same_as` string[], nullable - `subsets` string[], nullable: A list of subsets that the entity belongs to - `file_source` string, nullable: Source file stem injected by koza at load time. - `provided_by` string, nullable - `full_name` string, nullable: The long form name of an entity - `symbol` string, nullable - `has_gene` string[], nullable - `type` string, nullable: The type of the entity (e.g. sequence onotology type for genes etc) - `has_attribute` string[], nullable - `has_biological_sex` string, nullable: The biological sex of an individual entity. - `synonyms` string, nullable - `namespace` string, nullable: The namespace/prefix portion of this entity's identifier - `has_phenotype` string[], nullable: A list of phenotype identifiers that are known to be associated with this entity - `has_phenotype_label` string[], nullable: A list of phenotype labels that are known to be associated with this entity - `has_phenotype_count` integer, nullable: A count of the number of phenotypes that are known to be associated with this entity - `has_phenotype_closure` string[], nullable: A list of phenotype identifiers that are known to be associated with this entity expanded to include all ancestors - `has_phenotype_closure_label` string[], nullable: A list of phenotype labels that are known to be associated with this entity expanded to include all ancestors - `has_descendant` string[], nullable: A list of entity identifiers that are known to be descendants of this entity - `has_descendant_label` string[], nullable: A list of entity labels that are known to be descendants of this entity - `has_descendant_count` integer, nullable: A count of the number of entities that are known to be descendants of this entity - `score` number, nullable - `matched_field` 'name' | 'exact_synonym' | 'broad_synonym' | 'narrow_synonym' | 'related_synonym': The entity field that a search query matched as a whole string - `match_type` 'exact' | 'synonym': How defensible a search hit is as an identification of the query text - `facet_fields` FacetField[], nullable: Collection of facet field responses with the field values and counts - `label` string, required - `facet_values` FacetValue[], nullable: Collection of FacetValue label/value instances belonging to a FacetField - `label` string, required - `count` integer, nullable: count of documents - `facet_queries` FacetValue[], nullable: Collection of facet query responses with the query string values and counts - `label` string, required - `count` integer, nullable: count of documents - `scope` SearchScopeResolution: The filters a named `scope` resolved to, echoed back so a caller can see what was filtered, log it, and reproduce or override it with the raw filter parameters. These are the filters actually applied, so an explicit parameter that overrode part of the scope is reflected here. - `name` string, nullable: The scope that was requested - `category` string[], nullable: The biolink categories the search was restricted to - `namespace` string[], nullable: The CURIE namespaces the search was restricted to - `exclude_namespace` string[], nullable: A CURIE namespace that entities were excluded by - `subset` string[], nullable: An ontology subset that entities were restricted to - `exclude_subset` string[], nullable: An ontology subset that entities were excluded by - `in_taxon` string[], nullable: The taxon CURIEs the search was restricted to - `in_taxon_label` string[], nullable: The taxon labels the search was restricted to ## Other responses - `404`: Not Found - `422`: Validation Error ## Changes - **2026-09-26** `00871419e83e`: 14 info - added the new optional `query` request parameter `exclude_namespace` - added the new optional `query` request parameter `exclude_subset` - added the new optional `query` request parameter `facets` - added the new optional `query` request parameter `in_taxon` - …10 more [Operation history](https://skmtc.dev/monarchinitiative/apis/monarchinitiative-api/changes/v3/api/search/get.md) --- [API](https://skmtc.dev/monarchinitiative/apis/monarchinitiative-api.md) - [All operations](https://skmtc.dev/monarchinitiative/apis/monarchinitiative-api/llms.txt) - [OpenAPI document](https://skmtc.dev/monarchinitiative/apis/monarchinitiative-api/revisions/00871419e83e?raw)