> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Search API > How to expose custom application data to the Itential Platform search engine using search objects and MongoDB indexes. The Search API provides a way to search MongoDB databases, as long as your data is properly exposed to the Itential Platform search engine. This guide explains how to set indexes and expose your data collections using search objects. Only use this guide to modify custom applications. Do not modify or update Itential applications. ## Expose an application for searching A database collection can be searched if it is exposed with a search object. This search object is added to the `pronghorn.json` file and consists of an object, or array of objects, following the schema below. ### Search object attributes | Attribute | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `label` | The name of the application displayed in search results. For example: `Mop Template` or `Workflow`. | | `collection` | The name of the collection to search. | | `fields` | An array of objects containing fields to search. Each object has a `name` (the field name) and a `type` (the data type — only `string` is supported). | | `map` | An object that formats the returned data. `name`: a field name reference (for example, `title`). `description`: a field name reference — can be null if the database results have no description. `url`: the absolute path for accessing found content, using mustache template syntax such as `{{variable}}`. Available variables include your exposed field values plus `mongo_id`. | ### Examples **Empty search template** ```json "search": { "label": "YOUR APP NAME", "collection": "DATABASE COLLECTION NAME", "fields": [ { "name": "FIELD TITLE", "type": "string" } ], "map": { "name": "FIELD REFERENCE NAME", "description": "FIELD REFERENCE NAME (can be null or empty)", "url": "/myapp/{{EXAMPLE_VAR}}?myvar={{EXAMPLE_VAR}}" } } ``` **Search exposure object** ```json "search": { "label": "Mop", "collection": "mop_templates", "fields": [ { "name": "name", "type": "string" } ], "map": { "name": "name", "description": null, "url": "/mop/template?name={{name}}" } } ``` Currently, only text-based fields (`"type": "string"`) are supported for searching. ## Create an index for exposed collections You must create the appropriate indexes for your fields to be search-enabled. MongoDB uses compound indexes — list each field name followed by `1` as the value. The compound index must match the fields in the search template. For example, if you want to search on `name` and `type`, you must have a compound index on both fields. To create an index against a local instance for testing, run the following in a MongoDB collection browser. This example creates an index on the MOP templates collection for `name`: ```javascript db.getCollection('mop_templates').createIndex({ "name": 1 }, { background: true }); ``` Follow these guidelines when creating indexes: * Avoid creating too many indexes. Excess indexes slow down inserts into the database. * Always set `background` to `true` when creating indexes to support performance at scale. * Test the addition of search objects in a lab environment to monitor performance before releasing to production. ## Make a search request | Search API endpoint | Method | Path | | ------------------- | ------ | -------------- | | Search | POST | `/search/find` | The POST body consists of a `data` object with a `text` property containing the value to search for. **Empty request** ```json { "data": { "text": "TEXT TO SEARCH ON" } } ``` **Search object example** (searching for the word `workflow`): ```json { "data": { "text": "workflow" } } ``` ### Search results Results follow the map object configured above, with the addition of `_id` and `tags` fields: ```json { "results": [ { "label": "Mop", "type": "mop_templates", "results": [ { "_id": "workflow helper", "name": "workflow helper", "description": "", "url": "/mop/template?name=workflow%20helper", "tags": [ { "_id": "5c37ada0788ede01a2b62b47", "name": "Awesome", "description": "Sauce" } ] }, { "_id": "workflow helper two", "name": "workflow helper two", "description": "", "url": "/mop/template?name=workflow%20helper%20two", "tags": [] } ], "count": 2 }, { "label": "Workflows", "type": "workflows", "results": [ { "_id": "51fdc757-076a-41d6-9e51-bf7856aabb28", "name": "Delay Workflow", "description": "", "url": "/workflow_builder/edit?name=Delay%20Workflow", "tags": [] } ], "count": 1 } ], "totalCount": 3 } ``` **Top-level result fields** | Field | Type | Description | | ------------ | ------ | ------------------------------------------ | | `results` | Array | Search results grouped by collection type. | | `totalCount` | Number | Total count of all results. | **Result group fields** | Field | Type | Description | | --------- | ------ | ----------------------------------- | | `label` | String | Display name. | | `type` | String | Collection name. | | `results` | Array | Array of results. | | `count` | Number | Total results count for this group. | **Individual search result fields** | Field | Type | Description | | ------------- | ------ | ------------------------------- | | `_id` | String | The ID of the search result. | | `name` | String | Name of the result. | | `description` | String | Description of the result. | | `url` | String | URL path to access the content. | | `tags` | Array | List of tags for the result. | ## Currently supported Itential applications The following Itential applications already have search objects and indexes configured: | Application | Search-enabled fields | | ------------- | --------------------- | | Workflow | Name | | Mop Templates | Name | | Forms | Name | | Golden Config | Name | ## Additional information The Search REST API is currently used only by the site-wide search box in the top navigation bar. You can, however, use the results in your own application if needed.