> For the complete documentation index, see [llms.txt](https://raic-labs.gitbook.io/raic-fed/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://raic-labs.gitbook.io/raic-fed/api-reference/04a-foundry-api/search.md).

# Search

## Search

> Create a new search

```json
{"openapi":"3.1.0","info":{"title":"Foundry Api","version":"0.1.0"},"servers":[{"url":"/foundry"}],"paths":{"/search":{"post":{"tags":["search"],"summary":"Search","description":"Create a new search","operationId":"search_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponseDetails"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"SearchRequest":{"properties":{"metadetectionIds":{"items":{"type":"string"},"type":"array","title":"Metadetectionids","default":[]},"toi":{"anyOf":[{"$ref":"#/components/schemas/ToiRequest"},{"type":"null"}]},"aoi":{"anyOf":[{"$ref":"#/components/schemas/AoiRequest"},{"type":"null"}]},"taxonomyCategoryIds":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Taxonomycategoryids"},"includeTaxonomyCategoryItems":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Includetaxonomycategoryitems","default":false},"targetWidthMeters":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Targetwidthmeters"},"targetLengthMeters":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Targetlengthmeters"},"scoutModelId":{"type":"integer","title":"Scoutmodelid"}},"type":"object","required":["scoutModelId"],"title":"SearchRequest","description":"SearchRequest model for starting a new search.\nParameters:\n    metadetection_ids (list[str], default=[]):\n        List of metadetection ids used as the reference embedding to search for similar embeddings.\n    toi (Optional[ToiRequest], default=None):\n        An optional time-of-interest object that defines the search time interval.\n    aoi (Optional[AoiRequest], default=None):\n        An optional area-of-interest object. Provide geometry (list of GeoJSON dicts) to filter\n        results spatially, or provide stac_item_id and stac_collection_id to use an existing AOI (NotImplementedYet).\n    include_taxonomy_category_items (Optional[bool], default=False):\n        When False (default), search results exclude items already categorized in taxonomy.\n        When True, search results include all items regardless of taxonomy categorization."},"ToiRequest":{"properties":{"start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start"},"end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End"}},"type":"object","title":"ToiRequest","description":"Time of Interest request class for handling datetime ranges.\n\n`start` and `end` can be:\n- An ISO 8601 datetime (e.g., \"2018-02-12T00:00:00Z\")\n- None to specify an open interval\n\nArgs:\n    start: The start of the time range (None for open start interval)\n    end: The end of the time range (None for open end interval)\n\nThe string representation of a TOI is \"start/end\", where each part can be an ISO datetime or \"..\" for open intervals when start or end is None.\n\nString Examples:\n- `\"2018-02-12T00:00:00+00:00/2018-03-18T12:31:12+00:00\"`\n- `\"../2018-03-18T12:31:12+00:00\"` if start is None\n- `\"2018-02-12T00:00:00+00:00/..\"` if end is None"},"AoiRequest":{"properties":{"stacItemId":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stacitemid"},"stacCollectionId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Staccollectionid"},"geometry":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Geometry"}},"type":"object","title":"AoiRequest","description":"Area of interest request.\nParameters:\n    stac_item_id (Optional[int], default=None):\n        ID of an existing AOI STAC item.\n    stac_collection_id (Optional[str], default=None):\n        STAC collection the AOI belongs to.\n    geometry (Optional[list[dict]], default=None):\n        List of GeoJSON geometry objects defining the AOI.\n        Mutually exclusive with STAC identifiers. If provided, a new AOI is created."},"SearchResponseDetails":{"properties":{"searchId":{"type":"integer","title":"Searchid"},"status":{"type":"string","title":"Status"},"completedOn":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completedon"},"durationMs":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Durationms"},"tiffsSearched":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tiffssearched"},"toi":{"anyOf":[{"$ref":"#/components/schemas/ToiResponse"},{"type":"null"}]},"aoi":{"anyOf":[{"$ref":"#/components/schemas/AoiResponse"},{"type":"null"}]},"queryImageDetails":{"anyOf":[{"items":{"$ref":"#/components/schemas/QueryImageDetailsResponse"},"type":"array"},{"type":"null"}],"title":"Queryimagedetails"},"scoutModelName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scoutmodelname"},"isPinned":{"type":"boolean","title":"Ispinned","default":false},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"results":{"anyOf":[{"items":{"$ref":"#/components/schemas/SearchResultResponse"},"type":"array"},{"type":"null"}],"title":"Results"},"contextMap":{"anyOf":[{"$ref":"#/components/schemas/ContextMapResponse"},{"type":"null"}]}},"type":"object","required":["searchId","status"],"title":"SearchResponseDetails"},"ToiResponse":{"properties":{"start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start"},"end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End"}},"type":"object","title":"ToiResponse"},"AoiResponse":{"properties":{"stacItemId":{"type":"integer","title":"Stacitemid"},"stacCollectionId":{"type":"string","title":"Staccollectionid"}},"type":"object","required":["stacItemId","stacCollectionId"],"title":"AoiResponse"},"QueryImageDetailsResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"frameStacId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Framestacid"},"cropBbox":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"null"}],"title":"Cropbbox"},"isExternalImage":{"type":"boolean","title":"Isexternalimage","default":false}},"type":"object","required":["id"],"title":"QueryImageDetailsResponse"},"SearchResultResponse":{"properties":{"metadetectionId":{"type":"string","title":"Metadetectionid"},"frameStacId":{"type":"string","title":"Framestacid"},"acquiredOn":{"type":"string","format":"date-time","title":"Acquiredon"},"bbox":{"items":{"type":"number"},"type":"array","title":"Bbox"},"geometry":{"anyOf":[{"items":{"items":{"type":"number"},"type":"array"},"type":"array"},{"type":"null"}],"title":"Geometry"},"nativeCrs":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nativecrs"},"nativeCrsBbox":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"null"}],"title":"Nativecrsbbox"},"score":{"type":"number","title":"Score","default":0},"contextMapX":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Contextmapx"},"contextMapY":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Contextmapy"}},"type":"object","required":["metadetectionId","frameStacId","acquiredOn","bbox"],"title":"SearchResultResponse"},"ContextMapResponse":{"properties":{"gridSize":{"type":"integer","title":"Gridsize"}},"type":"object","required":["gridSize"],"title":"ContextMapResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## GET /search/history

> Get User Search History

```json
{"openapi":"3.1.0","info":{"title":"Foundry Api","version":"0.1.0"},"servers":[{"url":"/foundry"}],"paths":{"/search/history":{"get":{"tags":["search"],"summary":"Get User Search History","operationId":"get_user_search_history_search_history_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"items":{"$ref":"#/components/schemas/SearchResponse"},"type":"array"},"type":"object","title":"Response Get User Search History Search History Get"}}}},"404":{"description":"Not found"}}}}},"components":{"schemas":{"SearchResponse":{"properties":{"searchId":{"type":"integer","title":"Searchid"},"status":{"type":"string","title":"Status"},"completedOn":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completedon"},"durationMs":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Durationms"},"tiffsSearched":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tiffssearched"},"toi":{"anyOf":[{"$ref":"#/components/schemas/ToiResponse"},{"type":"null"}]},"aoi":{"anyOf":[{"$ref":"#/components/schemas/AoiResponse"},{"type":"null"}]},"queryImageDetails":{"anyOf":[{"items":{"$ref":"#/components/schemas/QueryImageDetailsResponse"},"type":"array"},{"type":"null"}],"title":"Queryimagedetails"},"scoutModelName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scoutmodelname"},"isPinned":{"type":"boolean","title":"Ispinned","default":false},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["searchId","status"],"title":"SearchResponse"},"ToiResponse":{"properties":{"start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start"},"end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End"}},"type":"object","title":"ToiResponse"},"AoiResponse":{"properties":{"stacItemId":{"type":"integer","title":"Stacitemid"},"stacCollectionId":{"type":"string","title":"Staccollectionid"}},"type":"object","required":["stacItemId","stacCollectionId"],"title":"AoiResponse"},"QueryImageDetailsResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"frameStacId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Framestacid"},"cropBbox":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"null"}],"title":"Cropbbox"},"isExternalImage":{"type":"boolean","title":"Isexternalimage","default":false}},"type":"object","required":["id"],"title":"QueryImageDetailsResponse"}}}}
```

## GET /search/{search\_id}

> Get Search

```json
{"openapi":"3.1.0","info":{"title":"Foundry Api","version":"0.1.0"},"servers":[{"url":"/foundry"}],"paths":{"/search/{search_id}":{"get":{"tags":["search"],"summary":"Get Search","operationId":"get_search_search__search_id__get","parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"integer","title":"Search Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## DELETE /search/{search\_id}

> Delete Search

```json
{"openapi":"3.1.0","info":{"title":"Foundry Api","version":"0.1.0"},"servers":[{"url":"/foundry"}],"paths":{"/search/{search_id}":{"delete":{"tags":["search"],"summary":"Delete Search","operationId":"delete_search_search__search_id__delete","parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"integer","title":"Search Id"}}],"responses":{"204":{"description":"Successful Response"},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## PATCH /search/{search\_id}

> Update Search

```json
{"openapi":"3.1.0","info":{"title":"Foundry Api","version":"0.1.0"},"servers":[{"url":"/foundry"}],"paths":{"/search/{search_id}":{"patch":{"tags":["search"],"summary":"Update Search","operationId":"update_search_search__search_id__patch","parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"integer","title":"Search Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"UpdateSearchRequest":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"isPinned":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ispinned"}},"type":"object","title":"UpdateSearchRequest"},"SearchResponse":{"properties":{"searchId":{"type":"integer","title":"Searchid"},"status":{"type":"string","title":"Status"},"completedOn":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completedon"},"durationMs":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Durationms"},"tiffsSearched":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tiffssearched"},"toi":{"anyOf":[{"$ref":"#/components/schemas/ToiResponse"},{"type":"null"}]},"aoi":{"anyOf":[{"$ref":"#/components/schemas/AoiResponse"},{"type":"null"}]},"queryImageDetails":{"anyOf":[{"items":{"$ref":"#/components/schemas/QueryImageDetailsResponse"},"type":"array"},{"type":"null"}],"title":"Queryimagedetails"},"scoutModelName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scoutmodelname"},"isPinned":{"type":"boolean","title":"Ispinned","default":false},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["searchId","status"],"title":"SearchResponse"},"ToiResponse":{"properties":{"start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start"},"end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End"}},"type":"object","title":"ToiResponse"},"AoiResponse":{"properties":{"stacItemId":{"type":"integer","title":"Stacitemid"},"stacCollectionId":{"type":"string","title":"Staccollectionid"}},"type":"object","required":["stacItemId","stacCollectionId"],"title":"AoiResponse"},"QueryImageDetailsResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"frameStacId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Framestacid"},"cropBbox":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"null"}],"title":"Cropbbox"},"isExternalImage":{"type":"boolean","title":"Isexternalimage","default":false}},"type":"object","required":["id"],"title":"QueryImageDetailsResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## POST /search/{search\_id}/cancel

> Cancel Search

```json
{"openapi":"3.1.0","info":{"title":"Foundry Api","version":"0.1.0"},"servers":[{"url":"/foundry"}],"paths":{"/search/{search_id}/cancel":{"post":{"tags":["search"],"summary":"Cancel Search","operationId":"cancel_search_search__search_id__cancel_post","parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"integer","title":"Search Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```