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

# Update productivity assistant

PATCH https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/{id}
Content-Type: application/json

Changes the fields you send and returns the full updated assistant.

Send only the fields you want to change, plus `version` with the `num` from your last read. A field you leave out keeps its stored value, an explicit `null` clears it, and every list is replaced whole. The assistant's `id` goes in the URL; if you also send `id` in the body it must match.

For the rules that apply to specific fields, see [How productivity assistant updates behave](/api-reference/configuration-api/productivity-assistants/overview#how-productivity-assistant-updates-behave).

Reference: https://docs.moveworks.com/api-reference/configuration-api/productivity-assistants/update-productivity-assistant

## Authentication

- `Authorization` header (bearer token, required) — JWT bearer token authentication. Include the Configuration API key in the Authorization header as 'Bearer \<token>'.

## Request

### Path parameters

- `id` (string, required) — The `id` of the productivity assistant, as returned when it was created or listed.

### Body (application/json)

This endpoint expects an UpdateProductivityAssistantRequest.

- `version` (VersionOnUpdate, required) — The version you last read, and a note for this change.
- `name` (string, optional) — Display name of the assistant. Must be unique in your organization.
- `description` (string, optional) — What the assistant does. Shown to users when they choose an assistant.
- `welcome_message` (string, optional) — Message shown when a user opens the assistant.
- `icon` (string, optional) — Name of the assistant's icon in the Moveworks icon set, for example `MWIconPublic`. This is a name, not a URL.
- `instructions` (string, optional) — Instructions that shape the assistant's behavior.
- `conversation_starters` (list of ConversationStarter, optional) — Suggested prompts shown in a new conversation. Up to 10.
- `plugin_identifiers` (list of string, optional) — Plugins the assistant can use. Each value is a built-in plugin name such as `enterprise_search_plugin`, or the id of a custom plugin. An empty list means no plugins. While `knowledge_scope` has at least one entry, the API keeps `enterprise_search_plugin` in this list for you.
- `knowledge_scope` (KnowledgeScope, optional) — Limits the assistant's enterprise search to the systems, documents, workspaces and channels you list. The assistant searches the combined set. Leave the scope out, or send every list empty, to search everything the user can already access.
- `skill_access_mode` (enum, optional) — Which Skills the assistant can use. - `ALL` - every Skill in your organization, including Skills registered later. - `SELECTED` - only the Skills in `skill_ids`. If you leave this out when you create an assistant, the API stores `SELECTED`, so the assistant gets no Skills you didn't list. On update, leaving it out keeps the stored mode.
  - Allowed values: `ALL`, `SELECTED`
- `skill_ids` (list of string, optional) — Ids of the Skills the assistant can use when `skill_access_mode` is `SELECTED`. Each id must belong to a Skill registered in your organization.
- `mcp_server_ids` (list of string, optional) — Ids of the MCP servers whose tools the assistant can call. Each server must already be connected for your organization.
- `a2a_agent_ids` (list of string, optional) — Ids of the A2A agents the assistant can delegate to. Each agent must already be registered for your organization.
- `user_access` (UserAccess, optional) — Who can use the assistant. Send exactly one option. Required on create, because every assistant needs an audience. On update, leave it out to keep the stored audience. The person who created the assistant always keeps access.

## Response

### 200

The updated productivity assistant, at its new version

- `id` (string, required) — Unique identifier of the assistant, assigned by the server.
- `name` (string, required) — Display name of the assistant. Must be unique in your organization.
- `version` (Version, required) — The version of a stored document.
- `description` (string, optional) — What the assistant does. Shown to users when they choose an assistant.
- `welcome_message` (string, optional) — Message shown when a user opens the assistant.
- `icon` (string, optional) — Name of the assistant's icon in the Moveworks icon set, for example `MWIconPublic`. This is a name, not a URL.
- `instructions` (string, optional) — Instructions that shape the assistant's behavior.
- `conversation_starters` (list of ConversationStarter, optional) — Suggested prompts shown in a new conversation. Up to 10.
- `plugin_identifiers` (list of string, optional) — Plugins the assistant can use. Each value is a built-in plugin name such as `enterprise_search_plugin`, or the id of a custom plugin. An empty list means no plugins. While `knowledge_scope` has at least one entry, the API keeps `enterprise_search_plugin` in this list for you.
- `knowledge_scope` (KnowledgeScope, optional) — Limits the assistant's enterprise search to the systems, documents, workspaces and channels you list. The assistant searches the combined set. Leave the scope out, or send every list empty, to search everything the user can already access.
- `skill_access_mode` (enum, optional) — Which Skills the assistant can use. - `ALL` - every Skill in your organization, including Skills registered later. - `SELECTED` - only the Skills in `skill_ids`. If you leave this out when you create an assistant, the API stores `SELECTED`, so the assistant gets no Skills you didn't list. On update, leaving it out keeps the stored mode.
  - Allowed values: `ALL`, `SELECTED`
- `skill_ids` (list of string, optional) — Ids of the Skills the assistant can use when `skill_access_mode` is `SELECTED`. Each id must belong to a Skill registered in your organization.
- `mcp_server_ids` (list of string, optional) — Ids of the MCP servers whose tools the assistant can call. Each server must already be connected for your organization.
- `a2a_agent_ids` (list of string, optional) — Ids of the A2A agents the assistant can delegate to. Each agent must already be registered for your organization.
- `user_access` (UserAccess, optional) — Who can use the assistant. Send exactly one option. Required on create, because every assistant needs an audience. On update, leave it out to keep the stored audience. The person who created the assistant always keeps access.
- `updated_time` (datetime, optional) — When the assistant was last updated.
- `updated_by` (string, optional) — Who last updated the assistant.

## Errors

### 400 Bad Request Error

Bad request - a field breaks a rule in the schema; `version.num` or `version.change_description` is missing; `user_access` is `null`, names two options or sets `allow_all` to `false`; an `id` in the body differs from the `id` in the URL; or an id in `skill_ids`, `mcp_server_ids`, `a2a_agent_ids` or `plugin_identifiers` doesn't exist in your organization

- `error` (ErrorResponseError, required)

### 401 Unauthorized Error

Unauthorized - the `Authorization` header is missing or the token is invalid

- `error` (ErrorResponseError, required)

### 403 Forbidden Error

Forbidden - the API key's user isn't allowed to read or change productivity assistants

- `error` (ErrorResponseError, required)

### 404 Not Found Error

Not found - no productivity assistant has this `id`

- `error` (ErrorResponseError, required)

### 409 Conflict Error

Conflict - `version.num` is out of date (read the assistant again and retry); another assistant already uses the new `name`; or the assistant can't be read or updated through this API, because its knowledge scope or plugin setup uses a shape the API can't express. Edit it in Assistant Builder instead.

- `error` (ErrorResponseError, required)

### 429 Too Many Requests Error

Too many requests - the organization exceeded the Configuration API rate limit. Back off and retry.

- `error` (ErrorResponseError, required)

### 500 Internal Server Error

Internal server error - retry the request

- `error` (ErrorResponseError, required)

## Types

### VersionOnUpdate

The version you last read, and a note for this change.

- `num` (integer, required) — The `version.num` from your last read. If the document changed since then, the update is rejected with `409`.
- `change_description` (string, required) — A short note describing this change. Required.

### ConversationStarter

A suggested prompt shown in a new conversation.

- `display_text` (string, required) — Short label shown on the suggestion.
- `utterance` (string, required) — Full message sent when the user selects the suggestion.

### KnowledgeScope

Limits the assistant's enterprise search to the systems, documents, workspaces and channels you list. The assistant searches the combined set. Leave the scope out, or send every list empty, to search everything the user can already access.

- `systems` (list of string, optional) — External systems to search in full, for example `CONFLUENCE` or `SHAREPOINT`. Up to 50.
- `documents` (list of KnowledgeDocument, optional) — Individual documents to search. Up to 200.
- `workspaces` (list of KnowledgePartition, optional) — Workspaces to search, such as a SharePoint site. Up to 100.
- `channels` (list of KnowledgePartition, optional) — Channels to search, such as a Slack channel. Up to 100. A channel must leave `filter_key` empty.

### UserAccess

Who can use the assistant. Send exactly one option. Required on create, because every assistant needs an audience. On update, leave it out to keep the stored audience. The person who created the assistant always keeps access.

- Everyone: UserAccessEveryone
- Listed users: UserAccessListedUsers
- DSL rule: UserAccessRule

### Version

The version of a stored document.

- `num` (integer, required) — Version number set by the server. Send it back on your next update.
- `change_description` (string, optional) — The note recorded with this version.

### ErrorResponseError

- `code` (string, optional) — A machine-readable error code.
- `message` (string, optional) — What went wrong, and for a rejected field, which rule it broke.

### KnowledgeDocument

One document the assistant can search.

- `external_system` (string, required) — The system the document belongs to.
- `mw_record_urn` (string, required) — The Moveworks record URN of the document.
- `title` (string, optional) — Document title. Display only.
- `source_icon_url` (string, optional) — Icon of the document's source. Display only.

### KnowledgePartition

A workspace or channel the assistant can search.

- `external_system` (string, required) — The system the workspace or channel belongs to.
- `value` (string, required) — The workspace key or channel id.
- `filter_key` (string, optional) — For a workspace, the name of the source attribute that `value` matches, for example `site`. Leave it empty for a channel.
- `label` (string, optional) — Display label.
- `icon_url` (string, optional) — Icon of the source. Display only.

### UserAccessEveryone

- `allow_all` (boolean, required) — Set to `true` to let every user in your organization use the assistant. `false` is rejected.

### UserAccessListedUsers

- `allowed_emails` (UserAccessListedUsersAllowedEmails, required) — Only the listed users can use the assistant.

### UserAccessRule

- `allowlist_rule_dsl` (string, required) — A Moveworks DSL rule over the `user` object, for example `user.department == "IT"`. Users for whom the rule is true can use the assistant. The rule's syntax is checked when you save. See the [Moveworks DSL reference](/api-reference/configuration-languages/moveworks-dsl-reference).

### UserAccessListedUsersAllowedEmails

Only the listed users can use the assistant.

- `email_addrs` (list of string, required) — Email addresses of the users who can use the assistant. Up to 1,000. Addresses match regardless of letter case.

## Examples

### Productivity assistant endpoints_updateProductivityAssistant_example

**Response**

```json
{
  "id": "7c2b6a1e-3f4d-4b8a-9c1d-2e5f6a7b8c9d",
  "name": "Helpdesk",
  "version": {
    "num": 2,
    "change_description": "Limit to IT"
  },
  "description": "Answers IT questions and files tickets.",
  "welcome_message": "Hi! How can I help with IT today?",
  "icon": "MWIconPublic",
  "instructions": "Be brief. Escalate hardware issues to the Helpdesk queue.",
  "conversation_starters": [
    {
      "display_text": "Reset my password",
      "utterance": "How do I reset my password?"
    }
  ],
  "plugin_identifiers": [
    "ticket_plugin",
    "enterprise_search_plugin"
  ],
  "knowledge_scope": {
    "systems": [
      "CONFLUENCE"
    ],
    "documents": [],
    "workspaces": [
      {
        "external_system": "SHAREPOINT",
        "value": "hr-site",
        "filter_key": "site",
        "label": "HR",
        "icon_url": ""
      }
    ],
    "channels": []
  },
  "skill_access_mode": "SELECTED",
  "skill_ids": [
    "9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f"
  ],
  "mcp_server_ids": [],
  "a2a_agent_ids": [
    "33333333-3333-4333-8333-333333333333"
  ],
  "user_access": {
    "allowlist_rule_dsl": "user.department == \"IT\""
  },
  "updated_time": "2026-11-13T09:30:00Z",
  "updated_by": "admin@example.com"
}
```

**SDK Code**

```python Productivity assistant endpoints_updateProductivityAssistant_example
import requests

url = "https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id"

headers = {"Authorization": "Bearer <token>"}

response = requests.patch(url, headers=headers)

print(response.json())
```

```javascript Productivity assistant endpoints_updateProductivityAssistant_example
const url = 'https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id';
const options = {method: 'PATCH', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Productivity assistant endpoints_updateProductivityAssistant_example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id"

	req, _ := http.NewRequest("PATCH", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Productivity assistant endpoints_updateProductivityAssistant_example
require 'uri'
require 'net/http'

url = URI("https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Productivity assistant endpoints_updateProductivityAssistant_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Productivity assistant endpoints_updateProductivityAssistant_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp Productivity assistant endpoints_updateProductivityAssistant_example
using RestSharp;

var client = new RestClient("https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Productivity assistant endpoints_updateProductivityAssistant_example
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Change the instructions and the audience

**Request**

```json
{
  "version": {
    "num": 1,
    "change_description": "Limit to IT"
  },
  "instructions": "Be brief. Escalate hardware issues to the Helpdesk queue.",
  "user_access": {
    "allowlist_rule_dsl": "user.department == \"IT\""
  }
}
```

**Response**

```json
{
  "id": "7c2b6a1e-3f4d-4b8a-9c1d-2e5f6a7b8c9d",
  "name": "Helpdesk",
  "version": {
    "num": 2,
    "change_description": "Limit to IT"
  },
  "description": "Answers IT questions and files tickets.",
  "welcome_message": "Hi! How can I help with IT today?",
  "icon": "MWIconPublic",
  "instructions": "Be brief. Escalate hardware issues to the Helpdesk queue.",
  "conversation_starters": [
    {
      "display_text": "Reset my password",
      "utterance": "How do I reset my password?"
    }
  ],
  "plugin_identifiers": [
    "ticket_plugin",
    "enterprise_search_plugin"
  ],
  "knowledge_scope": {
    "systems": [
      "CONFLUENCE"
    ],
    "documents": [],
    "workspaces": [
      {
        "external_system": "SHAREPOINT",
        "value": "hr-site",
        "filter_key": "site",
        "label": "HR",
        "icon_url": ""
      }
    ],
    "channels": []
  },
  "skill_access_mode": "SELECTED",
  "skill_ids": [
    "9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f"
  ],
  "mcp_server_ids": [],
  "a2a_agent_ids": [
    "33333333-3333-4333-8333-333333333333"
  ],
  "user_access": {
    "allowlist_rule_dsl": "user.department == \"IT\""
  },
  "updated_time": "2026-11-13T09:30:00Z",
  "updated_by": "admin@example.com"
}
```

**SDK Code**

```python Change the instructions and the audience
import requests

url = "https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id"

payload = {
    "version": {
        "num": 1,
        "change_description": "Limit to IT"
    },
    "instructions": "Be brief. Escalate hardware issues to the Helpdesk queue.",
    "user_access": { "allowlist_rule_dsl": "user.department == \"IT\"" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript Change the instructions and the audience
const url = 'https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"version":{"num":1,"change_description":"Limit to IT"},"instructions":"Be brief. Escalate hardware issues to the Helpdesk queue.","user_access":{"allowlist_rule_dsl":"user.department == \"IT\""}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Change the instructions and the audience
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id"

	payload := strings.NewReader("{\n  \"version\": {\n    \"num\": 1,\n    \"change_description\": \"Limit to IT\"\n  },\n  \"instructions\": \"Be brief. Escalate hardware issues to the Helpdesk queue.\",\n  \"user_access\": {\n    \"allowlist_rule_dsl\": \"user.department == \\\"IT\\\"\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Change the instructions and the audience
require 'uri'
require 'net/http'

url = URI("https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"version\": {\n    \"num\": 1,\n    \"change_description\": \"Limit to IT\"\n  },\n  \"instructions\": \"Be brief. Escalate hardware issues to the Helpdesk queue.\",\n  \"user_access\": {\n    \"allowlist_rule_dsl\": \"user.department == \\\"IT\\\"\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Change the instructions and the audience
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"version\": {\n    \"num\": 1,\n    \"change_description\": \"Limit to IT\"\n  },\n  \"instructions\": \"Be brief. Escalate hardware issues to the Helpdesk queue.\",\n  \"user_access\": {\n    \"allowlist_rule_dsl\": \"user.department == \\\"IT\\\"\"\n  }\n}")
  .asString();
```

```php Change the instructions and the audience
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id', [
  'body' => '{
  "version": {
    "num": 1,
    "change_description": "Limit to IT"
  },
  "instructions": "Be brief. Escalate hardware issues to the Helpdesk queue.",
  "user_access": {
    "allowlist_rule_dsl": "user.department == \\"IT\\""
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Change the instructions and the audience
using RestSharp;

var client = new RestClient("https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"version\": {\n    \"num\": 1,\n    \"change_description\": \"Limit to IT\"\n  },\n  \"instructions\": \"Be brief. Escalate hardware issues to the Helpdesk queue.\",\n  \"user_access\": {\n    \"allowlist_rule_dsl\": \"user.department == \\\"IT\\\"\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Change the instructions and the audience
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "version": [
    "num": 1,
    "change_description": "Limit to IT"
  ],
  "instructions": "Be brief. Escalate hardware issues to the Helpdesk queue.",
  "user_access": ["allowlist_rule_dsl": "user.department == \"IT\""]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Give the assistant a Skill (the list is replaced whole)

**Request**

```json
{
  "version": {
    "num": 2,
    "change_description": "Enable expense-report"
  },
  "skill_access_mode": "SELECTED",
  "skill_ids": [
    "9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f"
  ]
}
```

**Response**

```json
{
  "id": "7c2b6a1e-3f4d-4b8a-9c1d-2e5f6a7b8c9d",
  "name": "Helpdesk",
  "version": {
    "num": 2,
    "change_description": "Limit to IT"
  },
  "description": "Answers IT questions and files tickets.",
  "welcome_message": "Hi! How can I help with IT today?",
  "icon": "MWIconPublic",
  "instructions": "Be brief. Escalate hardware issues to the Helpdesk queue.",
  "conversation_starters": [
    {
      "display_text": "Reset my password",
      "utterance": "How do I reset my password?"
    }
  ],
  "plugin_identifiers": [
    "ticket_plugin",
    "enterprise_search_plugin"
  ],
  "knowledge_scope": {
    "systems": [
      "CONFLUENCE"
    ],
    "documents": [],
    "workspaces": [
      {
        "external_system": "SHAREPOINT",
        "value": "hr-site",
        "filter_key": "site",
        "label": "HR",
        "icon_url": ""
      }
    ],
    "channels": []
  },
  "skill_access_mode": "SELECTED",
  "skill_ids": [
    "9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f"
  ],
  "mcp_server_ids": [],
  "a2a_agent_ids": [
    "33333333-3333-4333-8333-333333333333"
  ],
  "user_access": {
    "allowlist_rule_dsl": "user.department == \"IT\""
  },
  "updated_time": "2026-11-13T09:30:00Z",
  "updated_by": "admin@example.com"
}
```

**SDK Code**

```python Give the assistant a Skill (the list is replaced whole)
import requests

url = "https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id"

payload = {
    "version": {
        "num": 2,
        "change_description": "Enable expense-report"
    },
    "skill_access_mode": "SELECTED",
    "skill_ids": ["9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript Give the assistant a Skill (the list is replaced whole)
const url = 'https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"version":{"num":2,"change_description":"Enable expense-report"},"skill_access_mode":"SELECTED","skill_ids":["9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Give the assistant a Skill (the list is replaced whole)
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id"

	payload := strings.NewReader("{\n  \"version\": {\n    \"num\": 2,\n    \"change_description\": \"Enable expense-report\"\n  },\n  \"skill_access_mode\": \"SELECTED\",\n  \"skill_ids\": [\n    \"9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Give the assistant a Skill (the list is replaced whole)
require 'uri'
require 'net/http'

url = URI("https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"version\": {\n    \"num\": 2,\n    \"change_description\": \"Enable expense-report\"\n  },\n  \"skill_access_mode\": \"SELECTED\",\n  \"skill_ids\": [\n    \"9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java Give the assistant a Skill (the list is replaced whole)
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"version\": {\n    \"num\": 2,\n    \"change_description\": \"Enable expense-report\"\n  },\n  \"skill_access_mode\": \"SELECTED\",\n  \"skill_ids\": [\n    \"9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f\"\n  ]\n}")
  .asString();
```

```php Give the assistant a Skill (the list is replaced whole)
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id', [
  'body' => '{
  "version": {
    "num": 2,
    "change_description": "Enable expense-report"
  },
  "skill_access_mode": "SELECTED",
  "skill_ids": [
    "9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Give the assistant a Skill (the list is replaced whole)
using RestSharp;

var client = new RestClient("https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"version\": {\n    \"num\": 2,\n    \"change_description\": \"Enable expense-report\"\n  },\n  \"skill_access_mode\": \"SELECTED\",\n  \"skill_ids\": [\n    \"9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Give the assistant a Skill (the list is replaced whole)
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "version": [
    "num": 2,
    "change_description": "Enable expense-report"
  ],
  "skill_access_mode": "SELECTED",
  "skill_ids": ["9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Clear the knowledge scope

**Request**

```json
{
  "version": {
    "num": 3,
    "change_description": "Search all content"
  },
  "knowledge_scope": {
    "systems": [],
    "documents": [],
    "workspaces": [],
    "channels": []
  }
}
```

**Response**

```json
{
  "id": "7c2b6a1e-3f4d-4b8a-9c1d-2e5f6a7b8c9d",
  "name": "Helpdesk",
  "version": {
    "num": 2,
    "change_description": "Limit to IT"
  },
  "description": "Answers IT questions and files tickets.",
  "welcome_message": "Hi! How can I help with IT today?",
  "icon": "MWIconPublic",
  "instructions": "Be brief. Escalate hardware issues to the Helpdesk queue.",
  "conversation_starters": [
    {
      "display_text": "Reset my password",
      "utterance": "How do I reset my password?"
    }
  ],
  "plugin_identifiers": [
    "ticket_plugin",
    "enterprise_search_plugin"
  ],
  "knowledge_scope": {
    "systems": [
      "CONFLUENCE"
    ],
    "documents": [],
    "workspaces": [
      {
        "external_system": "SHAREPOINT",
        "value": "hr-site",
        "filter_key": "site",
        "label": "HR",
        "icon_url": ""
      }
    ],
    "channels": []
  },
  "skill_access_mode": "SELECTED",
  "skill_ids": [
    "9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f"
  ],
  "mcp_server_ids": [],
  "a2a_agent_ids": [
    "33333333-3333-4333-8333-333333333333"
  ],
  "user_access": {
    "allowlist_rule_dsl": "user.department == \"IT\""
  },
  "updated_time": "2026-11-13T09:30:00Z",
  "updated_by": "admin@example.com"
}
```

**SDK Code**

```python Clear the knowledge scope
import requests

url = "https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id"

payload = {
    "version": {
        "num": 3,
        "change_description": "Search all content"
    },
    "knowledge_scope": {
        "systems": [],
        "documents": [],
        "workspaces": [],
        "channels": []
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript Clear the knowledge scope
const url = 'https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"version":{"num":3,"change_description":"Search all content"},"knowledge_scope":{"systems":[],"documents":[],"workspaces":[],"channels":[]}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Clear the knowledge scope
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id"

	payload := strings.NewReader("{\n  \"version\": {\n    \"num\": 3,\n    \"change_description\": \"Search all content\"\n  },\n  \"knowledge_scope\": {\n    \"systems\": [],\n    \"documents\": [],\n    \"workspaces\": [],\n    \"channels\": []\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Clear the knowledge scope
require 'uri'
require 'net/http'

url = URI("https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"version\": {\n    \"num\": 3,\n    \"change_description\": \"Search all content\"\n  },\n  \"knowledge_scope\": {\n    \"systems\": [],\n    \"documents\": [],\n    \"workspaces\": [],\n    \"channels\": []\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Clear the knowledge scope
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"version\": {\n    \"num\": 3,\n    \"change_description\": \"Search all content\"\n  },\n  \"knowledge_scope\": {\n    \"systems\": [],\n    \"documents\": [],\n    \"workspaces\": [],\n    \"channels\": []\n  }\n}")
  .asString();
```

```php Clear the knowledge scope
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id', [
  'body' => '{
  "version": {
    "num": 3,
    "change_description": "Search all content"
  },
  "knowledge_scope": {
    "systems": [],
    "documents": [],
    "workspaces": [],
    "channels": []
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Clear the knowledge scope
using RestSharp;

var client = new RestClient("https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"version\": {\n    \"num\": 3,\n    \"change_description\": \"Search all content\"\n  },\n  \"knowledge_scope\": {\n    \"systems\": [],\n    \"documents\": [],\n    \"workspaces\": [],\n    \"channels\": []\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Clear the knowledge scope
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "version": [
    "num": 3,
    "change_description": "Search all content"
  ],
  "knowledge_scope": [
    "systems": [],
    "documents": [],
    "workspaces": [],
    "channels": []
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.moveworks.ai/configurations/v1alpha1/assistant/productivity-assistants/id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```