# Search & Butler – API reference

> Smart search by meaning and the AI butler.

Smart search by meaning and the AI butler.

## Smart search

**`GET https://api.lifebutler.io/v1/workspaces/{workspaceId}/search`** · scope `search` · MCP tool `search`

Search by meaning across the whole workspace – appointments, tasks, list items, notes, documents incl. their content, contracts, … ("when is the car inspection due?", "Kita Rechnung"). Needs AI turned on for the workspace; free of credits.

### Path

| Field | Type | Description |
|---|---|---|
| `workspaceId` | string | Workspace id (from list_workspaces). |

### Query

| Field | Type | Description |
|---|---|---|
| `q` *(required)* | string |  |
| `limit` | integer |  Default: `10`. |

### Request

```bash
curl "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/search?q=stadtwerke" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY"
```

### Response `200`

| Field | Type | Description |
|---|---|---|
| `data` | array of SearchHit |  |
| `data[].type` | string | Where it lives: events, tasks, lists, notes, documents, contracts, … |
| `data[].id` | string | Id in that collection (for documents: use with get_document). |
| `data[].title` | string |  |
| `data[].snippet` | string |  |
| `data[].score` | number | Similarity 0–1, higher is closer. |

```json
{
  "data": [
    {
      "type": "string",
      "id": "Ab3Cd5Ef7G",
      "title": "Elternabend 3b",
      "snippet": "string",
      "score": 1
    }
  ]
}
```

## Ask the butler

**`POST https://api.lifebutler.io/v1/workspaces/{workspaceId}/butler`** · scope `butler` · MCP tool `ask_butler`

Ask in German or English about anything in the workspace (appointments, tasks, lists, documents, contracts, …) or tell it what to do ("Put pasta and eggs on the shopping list and remind me on Friday to call the dentist"). Returns the answer and proposed actions; with apply: true, lists items, tasks, appointments and notes are created right away (bills and meals stay proposals). Uses the workspace owner's credits like in the app (usually 1–2). Needs AI turned on for the workspace.

### Path

| Field | Type | Description |
|---|---|---|
| `workspaceId` | string | Workspace id (from list_workspaces). |

### Body

| Field | Type | Description |
|---|---|---|
| `question` *(required)* | string |  |
| `history` | array of object | Earlier turns of this conversation, oldest first. |
| `history[].role` *(required)* | `user` \| `assistant` |  |
| `history[].text` *(required)* | string |  |
| `apply` | boolean | Create the proposed items right away. Default: `false`. |

### Request

```bash
curl -X POST "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/butler" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Was steht diese Woche an?"}'
```

### Response `200`

| Field | Type | Description |
|---|---|---|
| `answer` | string |  |
| `actions` | array of ButlerAction |  |
| `actions[].type` | string | addListItems, createTask, createEvent, createNote, createBill or addMeal. |
| `applied` | integer | How many actions were carried out (apply: true). |
| `credits` | integer | Credits this answer cost. |

```json
{
  "answer": "Diese Woche stehen drei Termine an …",
  "actions": [
    {
      "type": "string"
    }
  ],
  "applied": 0,
  "credits": 1
}
```