> 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. # Productivity assistants (Configuration API) > Create, read and update Productivity Assistants through the Moveworks Configuration API: endpoints, fields at a glance and update rules. `assistant.productivity-assistants` The productivity assistants entity creates, reads and updates [Productivity Assistants](/ai-assistant/productivity-assistants/overview) through the Configuration API. It covers what you would otherwise set in Assistant Builder: the name, instructions, plugins, knowledge scope, Skills, MCP servers, A2A agents and audience. Deleting an assistant isn't available through the API. > **Controlled Availability** > > Productivity Assistants are in Controlled Availability. Capabilities, limits, and interface labels described here may change before general availability. To request access, contact your Moveworks account team. * **Endpoint:** `/assistant/productivity-assistants` | **Methods:** GET, PATCH, POST * **Request shape:** fields go at the top level of the JSON body. These endpoints take no `resource` wrapper, and the assistant's `id` goes in the URL, not the body. * **Schemas, examples and errors:** each endpoint page below lists every field with its limits, example requests and responses, and the errors it can return. ## Configuration API request basics | Setting | Value | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Base URL | `https://api.moveworks.ai/configurations/v1alpha1` | | Authentication | `Authorization: Bearer ` on every request. Moveworks issues Configuration API keys. The key identifies your organization, so no organization name goes in the URL. | | Content type | `application/json` | | Rate limit | 120 requests per minute for each organization. Above that, the API returns `429`; wait and retry. | | Versioning | Every create and update needs `version.change_description`. Every update also needs the `version.num` from your last read; if the document changed since then, the update returns `409`. | | Delete | Not available in `v1alpha1`. | ## Productivity assistant endpoints All paths are relative to the base URL above. | Method | Path | Endpoint reference | | ------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `POST` | `/assistant/productivity-assistants` | [Create productivity assistant](/api-reference/configuration-api/productivity-assistants/create-productivity-assistant) | | `GET` | `/assistant/productivity-assistants` | [List productivity assistants](/api-reference/configuration-api/productivity-assistants/list-productivity-assistants) | | `GET` | `/assistant/productivity-assistants/{id}` | [Get productivity assistant](/api-reference/configuration-api/productivity-assistants/get-productivity-assistant) | | `PATCH` | `/assistant/productivity-assistants/{id}` | [Update productivity assistant](/api-reference/configuration-api/productivity-assistants/update-productivity-assistant) | ## Productivity assistant fields at a glance This table says what each field is for. Types, limits and allowed values are on the [Create productivity assistant](/api-reference/configuration-api/productivity-assistants/create-productivity-assistant) page. | Field | What it sets | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | The assistant's display name. Required, and unique in your organization. | | `description` | What the assistant does, shown to users when they choose an assistant. | | `welcome_message` | The message shown when a user opens the assistant. | | `icon` | The assistant's icon, by its name in the Moveworks icon set. | | `instructions` | The instructions that shape the assistant's behavior. | | `conversation_starters` | Suggested prompts shown in a new conversation. | | `plugin_identifiers` | The plugins the assistant can use. | | `knowledge_scope` | The systems, documents, workspaces and channels that enterprise search is limited to. Leave it out to search everything the user can already access. | | `skill_access_mode` and `skill_ids` | Which Skills the assistant can use: every Skill, or only the ones you list. Register Skills with the [assistant skills](/api-reference/configuration-api/assistant-skills/overview) entity. | | `mcp_server_ids` | The MCP servers whose tools the assistant can call. | | `a2a_agent_ids` | The A2A agents the assistant can delegate to. | | `user_access` | Who can use the assistant: everyone, a list of email addresses, or a Moveworks DSL rule. Required on create. | | `version` | A note for this change, and on update the version number from your last read. | | `id`, `updated_time`, `updated_by` | Set by the server and returned in responses. | ## How productivity assistant updates behave A `PATCH` changes only what you send: * **A field you leave out stays as it is.** An explicit `null` clears the field. * **Lists are replaced whole.** This applies to `plugin_identifiers`, `skill_ids`, `mcp_server_ids`, `a2a_agent_ids`, `conversation_starters` and each list inside `knowledge_scope`. Send the complete list you want stored, including the items you're keeping. * **`user_access` stays as it is unless you send it.** Sending one option replaces the option that was stored. Sending `null` is rejected, because every assistant needs an audience. * **`skill_access_mode` is never widened by omission.** Leaving it out, or sending `null`, keeps the stored mode. * **While the knowledge scope has entries, `enterprise_search_plugin` stays in `plugin_identifiers`,** even if you leave it out of the list you send. * **To clear the knowledge scope,** send all four lists empty. After that, `enterprise_search_plugin` searches without a restriction until you remove it from `plugin_identifiers`. * **`version.num` must match the stored version.** If the assistant changed after your last read, the update is rejected with `409`. Read it again and retry. * **Settings this API doesn't expose are left unchanged,** for example a blocked-users list set in Assistant Builder. ## Assistants this API can't read or update Some assistants are rejected with `409` and are left out of the list response. Edit them in Assistant Builder instead. | Assistant | What the API does | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | Its knowledge scope uses a filter this API can't express | `GET` and `PATCH` return `409`. The API never returns it with an empty scope, so an update can't widen its access by accident. | | It has more than one plugin group or more than one knowledge scope | `GET` and `PATCH` return `409`. | | Your organization serves assistants from a storage path this API version doesn't write yet | `POST` and `PATCH` return `409`. | ## Related pages * [Assistant skills (Configuration API)](/api-reference/configuration-api/assistant-skills/overview): register the Skills you reference in `skill_ids` * [Create a Productivity Assistant](/ai-assistant/productivity-assistants/create-a-productivity-assistant): the same settings in Assistant Builder