> 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. # Replace skill bundle PATCH https://api.moveworks.ai/configurations/v1alpha1/assistant/skills/{id} Content-Type: application/json Replaces a Skill's bundle with a newly uploaded one and returns the updated Skill. Upload the new bundle with [Upload file](/api-reference/alpha-files-api/files/upload-file) first. `file_id` is the only field you can change: to change the description or surfaces, edit `SKILL.md` and upload a new bundle. The replacement must name the same Skill. Replacing a bundle with identical contents changes nothing and returns the current Skill, so a retry is safe. `version.num` is checked before the bundle is replaced, but two replacements sent at the same moment with the same `num` can both succeed, and the later one is stored. Reference: https://docs.moveworks.com/api-reference/configuration-api/assistant-skills/replace-skill-bundle ## Authentication - `Authorization` header (bearer token, required) — JWT bearer token authentication. Include the Configuration API key in the Authorization header as 'Bearer \'. ## Request ### Path parameters - `id` (string, required) — The `id` of the Skill, as returned when it was registered or listed. ### Body (application/json) This endpoint expects an UpdateSkillRequest. - `file_id` (string, required) — The Files API `id` of the replacement bundle, uploaded with purpose `CONFIGURATIONS_ASSISTANT_SKILL`. Its `SKILL.md` must name the same Skill. See [Upload file](/api-reference/alpha-files-api/files/upload-file). - `version` (VersionOnUpdate, required) — The version you last read, and a note for this change. ## Response ### 200 The updated Skill, at its new version - `id` (string, required) — Unique identifier of the Skill, assigned by the server. Use it in a productivity assistant's `skill_ids`. - `name` (string, required) — Skill name from the bundle's `SKILL.md`. Unique in your organization, and fixed once the Skill is created. - `version` (Version, required) — The version of a stored document. - `description` (string, optional) — Skill description from the bundle's `SKILL.md`. - `surfaces` (list of string, optional) — Where the Skill is available, from the `surfaces` list in the bundle's `SKILL.md`, for example `slack`. An empty list means everywhere. - `updated_time` (datetime, optional) — When the Skill was last updated. - `updated_by` (string, optional) — Who last updated the Skill. ## Errors ### 400 Bad Request Error Bad request - the same upload and bundle problems as when registering a Skill; a field other than `file_id` was sent; `version.num` or `version.change_description` is missing; or the replacement bundle names a different Skill - `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 replace this Skill - `error` (ErrorResponseError, required) ### 404 Not Found Error Not found - no Skill has this `id` - `error` (ErrorResponseError, required) ### 409 Conflict Error Conflict - `version.num` is out of date (read the Skill again and retry), or the uploaded file is still being scanned (retry in a few seconds) - `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. ### 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. ## Examples **Request** ```json { "file_id": "file_8kQ2m5Xw1Rt9LpZc4VnB3", "version": { "num": 1, "change_description": "Add mileage" } } ``` **Response** ```json { "id": "9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f", "name": "expense-report", "version": { "num": 2, "change_description": "Add mileage" }, "description": "Files expense reports from receipts and mileage logs.", "surfaces": [ "slack" ], "updated_time": "2026-11-13T09:45:00Z", "updated_by": "admin@example.com" } ``` **SDK Code** ```python Assistant skill endpoints_replaceSkillBundle_example import requests url = "https://api.moveworks.ai/configurations/v1alpha1/assistant/skills/id" payload = { "file_id": "file_8kQ2m5Xw1Rt9LpZc4VnB3", "version": { "num": 1, "change_description": "Add mileage" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Assistant skill endpoints_replaceSkillBundle_example const url = 'https://api.moveworks.ai/configurations/v1alpha1/assistant/skills/id'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"file_id":"file_8kQ2m5Xw1Rt9LpZc4VnB3","version":{"num":1,"change_description":"Add mileage"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Assistant skill endpoints_replaceSkillBundle_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.moveworks.ai/configurations/v1alpha1/assistant/skills/id" payload := strings.NewReader("{\n \"file_id\": \"file_8kQ2m5Xw1Rt9LpZc4VnB3\",\n \"version\": {\n \"num\": 1,\n \"change_description\": \"Add mileage\"\n }\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") 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 Assistant skill endpoints_replaceSkillBundle_example require 'uri' require 'net/http' url = URI("https://api.moveworks.ai/configurations/v1alpha1/assistant/skills/id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"file_id\": \"file_8kQ2m5Xw1Rt9LpZc4VnB3\",\n \"version\": {\n \"num\": 1,\n \"change_description\": \"Add mileage\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java Assistant skill endpoints_replaceSkillBundle_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.moveworks.ai/configurations/v1alpha1/assistant/skills/id") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"file_id\": \"file_8kQ2m5Xw1Rt9LpZc4VnB3\",\n \"version\": {\n \"num\": 1,\n \"change_description\": \"Add mileage\"\n }\n}") .asString(); ``` ```php Assistant skill endpoints_replaceSkillBundle_example request('PATCH', 'https://api.moveworks.ai/configurations/v1alpha1/assistant/skills/id', [ 'body' => '{ "file_id": "file_8kQ2m5Xw1Rt9LpZc4VnB3", "version": { "num": 1, "change_description": "Add mileage" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Assistant skill endpoints_replaceSkillBundle_example using RestSharp; var client = new RestClient("https://api.moveworks.ai/configurations/v1alpha1/assistant/skills/id"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"file_id\": \"file_8kQ2m5Xw1Rt9LpZc4VnB3\",\n \"version\": {\n \"num\": 1,\n \"change_description\": \"Add mileage\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Assistant skill endpoints_replaceSkillBundle_example import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "file_id": "file_8kQ2m5Xw1Rt9LpZc4VnB3", "version": [ "num": 1, "change_description": "Add mileage" ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.moveworks.ai/configurations/v1alpha1/assistant/skills/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() ```