# Search

The global search spotlight lets you quickly find resources, jump to pages, create new items, and browse documentation — all from a single overlay.

## UI, API, and MCP

Search is available through three channels with the same core ranking behavior but different authentication/context:

| Channel      | Entry point                                            | Authentication                         | Account scope                   |
| ------------ | ------------------------------------------------------ | -------------------------------------- | ------------------------------- |
| UI Spotlight | Header search / <code>⌘K</code> or <code>Ctrl+K</code> | Signed-in session (JWT)                | Current workspace account       |
| REST API     | <code>GET /api/search</code>                           | <code>X-API-Key</code>                 | Account associated with API key |
| MCP          | <code>search</code> MCP tool                           | <code>X-API-Key</code> (MCP transport) | Account associated with API key |

## Opening Search

There are three ways to open the search spotlight:

- **Keyboard shortcut** — Press **⌘K** (Mac) or **Ctrl+K** (Windows/Linux) from anywhere in the app.
- **Search bar** — Click the search input in the header (visible on desktop).
- **Search icon** — Tap the magnifying-glass icon in the header (visible on mobile).

## Resource Search

Type at least two characters to search across all your resources by **name** or **description**. Results are ranked so the best matches appear first:

1. **Prefix match** — resources whose name starts with your query.
2. **Substring match** — resources whose name contains your query.
3. **Description match** — resources whose description contains your query.

You can also paste a **UUID** directly into the search field to jump straight to that resource.

## Account Scoping

Search results are always scoped to the account currently selected in the app header.

- In personal workspaces, search runs against your personal account.
- In organization workspaces, search runs against that organization account.

If a request references an account you do not have access to, the authenticated search API returns **404 Not Found**.

## Entity Type Filter

Prefix your query with `type:<entity_type>` followed by a space to restrict results to a single entity type. For example:

- `type:agent support` — search for agents matching "support"
- `type:knowledge_base faq` — search for knowledge bases matching "faq"
- `type:alert billing` — search for alerts matching "billing"

## Searchable Entity Types

| Type              | Filter key                          | Description                          |
| ----------------- | ----------------------------------- | ------------------------------------ |
| Agent             | <code>type:agent</code>             | AI agents configured in your account |
| Knowledge Base    | <code>type:knowledge_base</code>    | Collections of content for agents    |
| Content Source    | <code>type:source_connection</code> | RSS feeds and websites               |
| Solution          | <code>type:solution</code>          | Bundled agent configurations         |
| Memory Bank       | <code>type:memory_bank</code>       | Conversation memory stores           |
| Alert             | <code>type:alert</code>             | Monitoring alerts                    |
| API Key           | <code>type:api_key</code>           | API access keys                      |
| Governance Policy | <code>type:governance_policy</code> | Compliance and governance policies   |

## Page Navigation

When search is open, you can also find top-level pages like Dashboard, Agents, Knowledge Bases, Sources, Settings, and more. Just start typing the page name.

## Quick Actions

Type "create" or "new" to see quick actions for creating new resources:

- Create new Agent
- Create new Solution
- Create new Knowledge Base
- Create new Content Source
- Create new Memory Bank
- Create new Governance Policy

## Documentation Search

All documentation pages are searchable from the spotlight. Type a topic name (e.g. "API keys", "alerts", "governance") to find and open the relevant docs page in a new tab.

## Recent Searches

Your last 5 search queries are saved locally and shown when you open the spotlight with an empty query. Recent searches are stored in your browser and are not synced across devices.

## Keyboard Shortcuts

Press **?** (question mark) anywhere in the app to open the keyboard shortcuts reference. Available shortcuts:

| Shortcut            | Action                           |
| ------------------- | -------------------------------- |
| **⌘K** / **Ctrl+K** | Open search                      |
| **Esc**             | Close search or dialog           |
| **↑ ↓**             | Navigate results                 |
| **Enter**           | Open selected result             |
| **?**               | Toggle keyboard shortcuts dialog |

## API Access

Search is also available through the public REST API:

```bash
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.seclai.com/api/search?q=my+agent&limit=10"
```

**Query parameters:**

| Parameter                | Required | Description                                                                  |
| ------------------------ | -------- | ---------------------------------------------------------------------------- |
| <code>q</code>           | Yes      | Search query (1–200 characters)                                              |
| <code>limit</code>       | No       | Maximum results (1–50, default: 10)                                          |
| <code>entity_type</code> | No       | Filter by entity type (e.g. <code>agent</code>, <code>knowledge_base</code>) |

**Response:**

```json
{
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "entity_type": "agent",
      "name": "My Support Agent",
      "description": "Handles customer support queries"
    }
  ]
}
```

For browser-session authenticated calls (JWT), Seclai also exposes:

```bash
GET /authenticated/search?q=...&account_id=...&limit=...&entity_type=...
```

In this endpoint, `account_id` is optional. If omitted, Seclai searches in your default account.
If an `account_id` is provided but not accessible to the user, this endpoint returns `404 Not Found`.

## MCP Server

If you use an MCP-compatible tool (such as Claude Code or Cursor), the `search` tool is available on the Seclai MCP server. It accepts the same `query`, `entity_type`, and `limit` parameters as the REST API and returns matching resources from your account.

Example MCP tool call:

```json
{
  "tool": "search",
  "arguments": {
    "query": "type:agent support",
    "entity_type": "agent",
    "limit": 10
  }
}
```

See the [MCP Server](https://seclai.com/docs/mcp) documentation for setup instructions.