> 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. # Register skill POST https://api.moveworks.ai/configurations/v1alpha1/assistant/skills Content-Type: application/json Registers a new Skill from an uploaded bundle and returns it with its `id`. Upload the `.zip` or `.skill` bundle first with [Upload file](/api-reference/alpha-files-api/files/upload-file), using purpose `CONFIGURATIONS_ASSISTANT_SKILL`, then send the returned file `id` here as `file_id` within 24 hours. The Skill's `name`, `description` and `surfaces` come from the bundle's `SKILL.md`, so you don't send them. The bundle must meet the [Skill bundle requirements](/api-reference/configuration-api/assistant-skills/overview#skill-bundle-requirements). Reference: https://docs.moveworks.com/api-reference/configuration-api/assistant-skills/register-skill ## Authentication - `Authorization` header (bearer token, required) — JWT bearer token authentication. Include the Configuration API key in the Authorization header as 'Bearer \'. ## Request ### Body (application/json) This endpoint expects a CreateSkillRequest. - `file_id` (string, required) — The Files API `id` of a `.zip` or `.skill` bundle uploaded with purpose `CONFIGURATIONS_ASSISTANT_SKILL`. See [Upload file](/api-reference/alpha-files-api/files/upload-file). The upload is consumed when the Skill is registered, so responses never include `file_id`. - `version` (VersionOnCreate, required) — The note to record with the new document. Don't send `num` on create. ## Response ### 200 The registered Skill - `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 `file_id` doesn't exist in your organization or the upload expired; the file was uploaded with a different purpose or isn't a `.zip` or `.skill` file; the bundle breaks a bundle requirement, such as a missing `SKILL.md` or an invalid `name`; the uploaded file failed its security scan; `name`, `description`, `surfaces`, `id` or `version.num` was sent; or `version.change_description` is missing - `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) ### 409 Conflict Error Conflict - another Skill already uses the `name` in the bundle's `SKILL.md`, or the uploaded file is still being scanned. For a scan in progress the message asks you to retry in a few seconds, and the same request succeeds once the scan finishes. - `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 ### VersionOnCreate The note to record with the new document. Don't send `num` on create. - `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_2yE5b2NC3Ypa2FszHbkh7", "version": { "change_description": "Add expense-report skill" } } ``` **Response** ```json { "id": "9e41c7d2-5a6b-4c3d-8e9f-1a2b3c4d5e6f", "name": "expense-report", "version": { "num": 1, "change_description": "Add expense-report skill" }, "description": "Files expense reports from receipts.", "surfaces": [ "slack" ], "updated_time": "2026-11-12T18:10:42Z", "updated_by": "admin@example.com" } ``` **SDK Code** ```python Assistant skill endpoints_registerSkill_example import requests url = "https://api.moveworks.ai/configurations/v1alpha1/assistant/skills" payload = { "file_id": "file_2yE5b2NC3Ypa2FszHbkh7", "version": { "change_description": "Add expense-report skill" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Assistant skill endpoints_registerSkill_example const url = 'https://api.moveworks.ai/configurations/v1alpha1/assistant/skills'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"file_id":"file_2yE5b2NC3Ypa2FszHbkh7","version":{"change_description":"Add expense-report skill"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Assistant skill endpoints_registerSkill_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.moveworks.ai/configurations/v1alpha1/assistant/skills" payload := strings.NewReader("{\n \"file_id\": \"file_2yE5b2NC3Ypa2FszHbkh7\",\n \"version\": {\n \"change_description\": \"Add expense-report skill\"\n }\n}") req, _ := http.NewRequest("POST", 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_registerSkill_example require 'uri' require 'net/http' url = URI("https://api.moveworks.ai/configurations/v1alpha1/assistant/skills") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"file_id\": \"file_2yE5b2NC3Ypa2FszHbkh7\",\n \"version\": {\n \"change_description\": \"Add expense-report skill\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java Assistant skill endpoints_registerSkill_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.moveworks.ai/configurations/v1alpha1/assistant/skills") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"file_id\": \"file_2yE5b2NC3Ypa2FszHbkh7\",\n \"version\": {\n \"change_description\": \"Add expense-report skill\"\n }\n}") .asString(); ``` ```php Assistant skill endpoints_registerSkill_example request('POST', 'https://api.moveworks.ai/configurations/v1alpha1/assistant/skills', [ 'body' => '{ "file_id": "file_2yE5b2NC3Ypa2FszHbkh7", "version": { "change_description": "Add expense-report skill" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Assistant skill endpoints_registerSkill_example using RestSharp; var client = new RestClient("https://api.moveworks.ai/configurations/v1alpha1/assistant/skills"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"file_id\": \"file_2yE5b2NC3Ypa2FszHbkh7\",\n \"version\": {\n \"change_description\": \"Add expense-report skill\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Assistant skill endpoints_registerSkill_example import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "file_id": "file_2yE5b2NC3Ypa2FszHbkh7", "version": ["change_description": "Add expense-report skill"] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.moveworks.ai/configurations/v1alpha1/assistant/skills")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" 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() ```