> 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.

# Domains

> Create, read and update Domains through the Moveworks Configuration API: endpoints, fields and examples.

`platform.domains`

* **Endpoint:** `/platform/domains`  |  **Methods:** GET, PATCH, POST
* **Request shape:** fields go at the top level of the JSON body, with no `resource` wrapper. The item's `id` goes in the URL for reads and updates, not in the body.
* **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`   | `/platform/domains`      | [List domains](/api-reference/configuration-api/platform-org/domains/list-domains)   |
| `POST`  | `/platform/domains`      | [Create domain](/api-reference/configuration-api/platform-org/domains/create-domain) |
| `GET`   | `/platform/domains/{id}` | [Get domain](/api-reference/configuration-api/platform-org/domains/get-domain)       |
| `PATCH` | `/platform/domains/{id}` | [Update domain](/api-reference/configuration-api/platform-org/domains/update-domain) |

### Fields

| Field               | Type           | Required  | Notes                                                                                                                                                      |
| ------------------- | -------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                | string         | read-only | Unique identifier of the domain, assigned by the server. Cannot be changed.                                                                                |
| `name`              | string         | ✅         | Name of the domain, for example Manufacturing. Must match a Smart Handoff category key (case insensitive) and be unique. Cannot be changed after creation. |
| `description`       | string         | ✅         | Description of the domain, used to decide when a request belongs to it. Required.                                                                          |
| `positive_examples` | array\<string> | ✅         | Example user requests that belong to this domain and boost its signal. 1 to 500 examples, each up to 250 characters.                                       |
| `negative_examples` | array\<string> |           | Example user requests that do not belong to this domain and reduce its signal. Up to 100 examples, each up to 250 characters.                              |
| `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.                                                                                        |

### Example create body

```json
{
  "name": "example-name",
  "description": "What this is for",
  "positive_examples": [
    "<string>"
  ],
  "negative_examples": [
    "<string>"
  ],
  "version": {
    "change_description": "Create domain"
  }
}
```