Skip to navigation
Configuration API (Alpha)Assistant skills

Assistant skills (Configuration API)

View as Markdown

assistant.skills

The assistant skills entity registers Skills from uploaded bundles, so that productivity assistants can use them. A Skill’s name, description and surfaces always come from the SKILL.md file in its bundle. The only thing you send is the file_id of a bundle uploaded through the Files API. Deleting a Skill 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/skills | Methods: GET, PATCH, POST
  • Request shape: fields go at the top level of the JSON body. These endpoints take no resource wrapper, and the Skill’s id goes in the URL, not the body.
  • Schemas, examples and errors: each endpoint page below lists every field, 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.

Assistant skill endpoints

Configuration API paths are relative to the base URL above. The upload is a Files API call with its own base URL.

MethodPathEndpoint reference
POSThttps://api.moveworks.ai/rest/v1alpha1/filesUpload file, with purpose CONFIGURATIONS_ASSISTANT_SKILL
POST/assistant/skillsRegister skill
GET/assistant/skillsList skills
GET/assistant/skills/{id}Get skill
PATCH/assistant/skills/{id}Replace skill bundle

Calls that register a Skill

Registering a Skill takes two calls, and a third to give it to an assistant.

OrderCallResult
1Upload file: send the .zip or .skill bundle with purpose CONFIGURATIONS_ASSISTANT_SKILL. The purpose part must come before the file part.A file id, valid for 24 hours.
2Register skill: send that id as file_id.The registered Skill, with its own id.
3Update productivity assistant: add the Skill’s id to skill_ids.The assistant can use the Skill.

The uploaded file is only a staging copy. Registering the Skill copies the bundle into permanent storage, so the Skill keeps working after the upload expires.

Skill bundle requirements

What goes inside a bundle, including the SKILL.md format, is described in Bundle format. These limits apply to a bundle sent through the API:

ItemRule
File type.zip or .skill, one Skill per file
Upload sizeUp to 100 MB
Unpacked sizeUp to 100 MiB, in up to 1,000 files
SKILL.md locationAt the root of the archive, or inside one folder named exactly as the Skill’s name
name1 to 64 characters: lowercase letters, digits and single hyphens
descriptionUp to 1,024 characters
Upload purposeCONFIGURATIONS_ASSISTANT_SKILL
Time to registerWithin 24 hours of the upload, before the file expires

How assistant skill updates behave

  • file_id is the only field you can change. A PATCH that sends name, description or surfaces is rejected. To change them, edit SKILL.md and upload a new bundle.
  • The Skill keeps its name. A replacement bundle whose SKILL.md names a different Skill is rejected. Register it as a new Skill instead.
  • Replacing a bundle with identical contents changes nothing. The request succeeds and returns the current Skill, so a retry is safe.
  • The last replacement wins. version.num is checked against the stored Skill before the bundle is replaced. Two replacements sent at the same moment with the same num can both succeed, and the later one is stored.
  • A rejected bundle doesn’t change the Skill. The bundle is checked before the Skill is created or replaced.
  • A bundle that is still being scanned returns 409. The message asks you to retry in a few seconds, and the same request succeeds once the scan finishes.