> This page is for API Reference & Tools.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# Handoff

> Read and update Handoff through the Moveworks Configuration API: endpoints, fields and examples.

`tool.handoff`

Categories + items. Lists patch WHOLESALE — send the full desired lists.

* **Endpoint:** `/tool/handoff`  |  **Methods:** GET, PATCH
* **Request shape:** one per organization, so there is no `id`. It already exists: read it with `GET`, then `PATCH` the fields you want to change. Fields go at the top level of the JSON body, with no `resource` wrapper.
* **Updates:** a JSON merge-patch. Send only the fields you change, plus `version: {num, change_description}` with the `num` from your last read. Lists and maps you send replace the stored ones whole.

### Endpoints

All paths are relative to `https://api.moveworks.ai/configurations/v1alpha1`. Each endpoint page lists the request and response schema, an example, and the errors it can return.

| Method  | Path            | Endpoint reference                                                                           |
| ------- | --------------- | -------------------------------------------------------------------------------------------- |
| `GET`   | `/tool/handoff` | [Get handoff](/api-reference/configuration-api/handoff-live-agent/handoff/get-handoff)       |
| `PATCH` | `/tool/handoff` | [Update handoff](/api-reference/configuration-api/handoff-live-agent/handoff/update-handoff) |

### Fields

| Field               | Type                           | Required  | Notes                                                                         |
| ------------------- | ------------------------------ | --------- | ----------------------------------------------------------------------------- |
| `category_settings` | array\<HandoffCategorySetting> |           | Handoff categories. Handoff items are grouped into categories by display key. |
| `item_settings`     | array\<HandoffItemSetting>     |           | Handoff items: the individual handoff options shown to users.                 |
| `updated_time`      | string                         | read-only | When the configuration was last updated.                                      |
| `updated_by`        | string                         | read-only | Who last updated the configuration.                                           |
| `version`           | Version                        |           | Document version. On update, send back the num from your last read.           |

### Document fields (example)

The document as `GET` returns it. To change any of these, send only the fields you want to change in the `PATCH` body.

```json
{
  "category_settings": [
    {
      "display_key": "<string>",
      "item_ref": "<string>"
    }
  ],
  "item_settings": [
    {
      "display_key": "<string>",
      "metadata": {},
      "endpoint_setting": {
        "endpoint_type": "HANDOFF_ENDPOINT_TYPE_DEFLECTION",
        "url": "https://example.com/path"
      },
      "pretrigger_rule_dsl": "true",
      "category_display_keys": [
        "<string>"
      ],
      "item_ref": "<string>"
    }
  ]
}
```