Skip to navigation
Configuration API (Alpha)Productivity assistants

Productivity assistants (Configuration API)

View as Markdown

assistant.productivity-assistants

The productivity assistants entity creates, reads and updates Productivity Assistants 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

SettingValue
Base URLhttps://api.moveworks.ai/configurations/v1alpha1
AuthenticationAuthorization: Bearer <MOVEWORKS_API_KEY> on every request. Moveworks issues Configuration API keys. The key identifies your organization, so no organization name goes in the URL.
Content typeapplication/json
Rate limit120 requests per minute for each organization. Above that, the API returns 429; wait and retry.
VersioningEvery 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.
DeleteNot available in v1alpha1.

Productivity assistant endpoints

All paths are relative to the base URL above.

MethodPathEndpoint reference
POST/assistant/productivity-assistantsCreate productivity assistant
GET/assistant/productivity-assistantsList productivity assistants
GET/assistant/productivity-assistants/{id}Get productivity assistant
PATCH/assistant/productivity-assistants/{id}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 page.

FieldWhat it sets
nameThe assistant’s display name. Required, and unique in your organization.
descriptionWhat the assistant does, shown to users when they choose an assistant.
welcome_messageThe message shown when a user opens the assistant.
iconThe assistant’s icon, by its name in the Moveworks icon set.
instructionsThe instructions that shape the assistant’s behavior.
conversation_startersSuggested prompts shown in a new conversation.
plugin_identifiersThe plugins the assistant can use.
knowledge_scopeThe 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_idsWhich Skills the assistant can use: every Skill, or only the ones you list. Register Skills with the assistant skills entity.
mcp_server_idsThe MCP servers whose tools the assistant can call.
a2a_agent_idsThe A2A agents the assistant can delegate to.
user_accessWho can use the assistant: everyone, a list of email addresses, or a Moveworks DSL rule. Required on create.
versionA note for this change, and on update the version number from your last read.
id, updated_time, updated_bySet 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.

AssistantWhat the API does
Its knowledge scope uses a filter this API can’t expressGET 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 scopeGET and PATCH return 409.
Your organization serves assistants from a storage path this API version doesn’t write yetPOST and PATCH return 409.