> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.awork.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.awork.com/_mcp/server. # Links a workflow to the specified project. POST https://api.awork.com/api/v1/projects/{projectId}/linkworkflow Content-Type: application/json Links the specified workflow to the project and migrates existing statuses using the provided mapping. If the project has no statuses, workflow statuses are assigned automatically. Switching workflows requires mappings for existing statuses. The user must be the project creator or have `project-master-data:write` permission for the project. Reference: https://developers.awork.com/apiv1/workflows/post-project-link-workflow-by-project-id ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `projectId` (string, required) — The id of the project. ### Body (application/json) This endpoint expects a LinkWorkflowForm. - `workflowId` (string, required) — The Id of the workflow to link. - `projectStatusMapping` (list of ProjectStatusMappingEntry, optional, nullable) — Maps existing project status Ids to workflow project status Ids. Required if the project/template has existing project statuses. - `taskStatusMapping` (list of TaskStatusMappingEntry, optional, nullable) — Maps existing task status Ids to workflow task status Ids. Required if the project/template has existing task statuses. - `keepCustomFields` (boolean, optional, nullable) — Whether to keep existing non-workflow custom fields when linking the workflow. If false, existing non-workflow task custom fields will be deleted. Default: true (keep custom fields). - `keepCustomAutomations` (boolean, optional, nullable) — Whether to keep existing non-workflow automations when linking the workflow. If false, custom automations will be deleted. Default: true (keep custom automations). ## Response ### 200 OK - `name` (string, required) — The name of the Project. Max allowed length: 1000 characters. - `isPrivate` (boolean, optional) — Whether this is a private project only visible to members and the creator. Defaults to false. Can only be changed from public to private if no times have been tracked on this project. Can always be made public. - `description` (string, optional, nullable) — The project description. Max allowed length: 25000 characters. - `startDate` (string, optional, nullable) — The start date of the project. - `dueDate` (string, optional, nullable) — The due date of the project. - `companyId` (string, optional, nullable) — The id of the company. - `timeBudget` (integer, optional, nullable) — The time budget the project has, in seconds. - `isBillableByDefault` (boolean, optional, nullable) — Whether project times should be billable by default. - `projectTypeId` (string, optional, nullable) — The id of the project type of this project. - `color` (string, optional, nullable) — The color of the project for display purposes in awork. The supported colors are defined by the awork frontend. Can be null when no color assigned. - `deductNonBillableHours` (boolean, optional) — Whether to deduct non-billable hours from project budgets. - `isProjectKeyVisible` (boolean, optional, nullable) — Whether project key should be visible for this project. If null, it will use the workspace default setting. - `projectStatusId` (string, optional) — The id of the project status. - `projectTemplateId` (string, optional, nullable) — The id of the template which is used to create the project. - `publicProjectTemplateId` (string, optional, nullable) — The id of the public template which is used to create the project. - `workflowId` (string, optional, nullable) — The id of the workflow to link to the project. Cannot be specified if ProjectTemplateId is set. - `id` (string, optional) — Id of the project. - `projectKey` (string, optional, nullable) — The unique project key within the workspace (e.g., "NIKE"). Maximum 32 characters, uppercase letters, numbers, and dashes only. - `hasImage` (boolean, optional) — Whether the project has an image. - `createdOn` (string, optional) — The date this entity was created. - `createdBy` (string, optional) — The id of the user who created this entity. - `updatedOn` (string, optional) — The date this entity was last modified. - `updatedBy` (string, optional) — The id of the user who last modified this entity. - `closedOn` (string, optional, nullable) — The date the project was set to closed. - `closedBy` (string, optional, nullable) — The user who closed the project. - `createdByProjectTemplateId` (string, optional, nullable) — The id of the template the project was created from. - `projectType` (NestedTypeModel, optional) - `projectStatus` (ExtendedProjectStatusModel, optional) - `company` (NestedCompanyModelForProjects, optional) - `tags` (list of ProjectTagModel, optional, nullable) — The tags for this project. - `totalPlannedDurationWithHierarchy` (long, optional, nullable) — The total planned duration of the project with hierarchy, in seconds. Calculated based on the planned durations of tasks and task lists of the project. Sum of Sum(TotalPlannedDurationWithHierarchy of all task lists) and Sum(TotalPlannedDurationWithHierarchy of all parent tasks without list) - `tasksCount` (integer, optional, nullable) — The number of all tasks related to the project. - `tasksDoneCount` (integer, optional, nullable) — The number of all tasks in status 'done' related to the project. - `members` (list of ProjectMember, optional, nullable) — The members of this project. - `trackedDuration` (integer, optional, nullable) — The summed up duration of all time trackings for this project. - `customFields` (list of CustomField, optional, nullable) — Custom fields of the project. - `resourceVersion` (long, optional) — The version of the entity, updated on every modification, to the ticks in UTC. Not identical to UpdatedOn. - `teams` (list of TeamModel, optional, nullable) — The teams the project is associated to. - `isExternal` (boolean, optional) — True if this entity is coming from an external workspace (awork Connect). - `isRetainer` (boolean, optional) — Whether the project is a retainer project. Retainer projects have at least one retainer with budgets. - `isMultiAssignmentAllowed` (boolean, optional) — Indicates whether multi-assignment is allowed for tasks in this project's workspace. - `plannedDuration` (long, optional, nullable, deprecated) — The total planned time of the project, in seconds. The time is calculated as te sum of the planned duration by all project tasks. ## Errors ### 400 Bad Request Error Bad Request - `code` (string, required) — The error code. - `description` (string, required) — The description of the error. - `link` (string, required) — The link to the API documentation page. - `details` (list of string, optional, nullable) — A list of details describing the error. - `validationErrors` (list of ValidationErrorResponse, optional, nullable) — If a validation error occurred, this contains the validation errors for each property. - `traceId` (string, optional, nullable) — The request trace id for tracking the request. ### 401 Unauthorized Error Unauthorized - `code` (string, required) — The error code. - `description` (string, required) — The description of the error. - `link` (string, required) — The link to the API documentation page. - `details` (list of string, optional, nullable) — A list of details describing the error. - `validationErrors` (list of ValidationErrorResponse, optional, nullable) — If a validation error occurred, this contains the validation errors for each property. - `traceId` (string, optional, nullable) — The request trace id for tracking the request. ### 404 Not Found Error Not Found - `code` (string, required) — The error code. - `description` (string, required) — The description of the error. - `link` (string, required) — The link to the API documentation page. - `details` (list of string, optional, nullable) — A list of details describing the error. - `validationErrors` (list of ValidationErrorResponse, optional, nullable) — If a validation error occurred, this contains the validation errors for each property. - `traceId` (string, optional, nullable) — The request trace id for tracking the request. ## Types ### ProjectStatusMappingEntry Maps an existing project status to a workflow project status. - `oldProjectStatusId` (string, required) — The Id of the existing project status to replace. - `newProjectStatusId` (string, required) — The Id of the workflow project status to use instead. ### TaskStatusMappingEntry Maps an existing task status to a workflow task status. - `oldTaskStatusId` (string, required) — The Id of the existing task status to replace. - `newTaskStatusId` (string, required) — The Id of the workflow task status to use instead. ### NestedTypeModel - `id` (string, optional) — The identifier of the nested model. - `name` (string, optional, nullable) — The name of the entity. - `icon` (string, optional, nullable) — The icon of the type. - `isArchived` (boolean, optional) — Whether the type is archived. ### ExtendedProjectStatusModel - `id` (string, optional) — The identifier of the nested model. - `name` (string, optional, nullable) — The name of the entity. - `description` (string, optional, nullable) — The description of the type. - `type` (string, optional, nullable) — The type of the status. - `isArchived` (boolean, optional) — Whether the type is archived. - `typeOrder` (integer, optional) — The order of the status type. - `isExternal` (boolean, optional) — True if this entity is coming from an external workspace (awork Connect). ### NestedCompanyModelForProjects - `id` (string, optional) — The identifier of the nested model. - `name` (string, optional, nullable) — The name of the entity. - `hasImage` (boolean, optional) — Whether the company has a profile image. - `description` (string, optional, nullable) — The description of the company. - `tags` (list of DefaultTagModel, optional, nullable) — The tags of the company. ### ProjectTagModel A tag model used for the project. Do not delete, we need to create copies of the tag model for each entity to avoid issues with Automapper. - `id` (string, optional) - `name` (string, optional, nullable) — The name of the tag. - `color` (string, optional, nullable) — The color of the tag. ### ProjectMember - `id` (string, optional) — The id of the project member entity. - `userId` (string, optional) — The id of the user who is this project member. - `firstName` (string, optional, nullable) — The first name of the user. - `lastName` (string, optional, nullable) — The last name of the user. - `hasImage` (boolean, optional, nullable) — Whether the user has an image. - `projectRoleId` (string, optional) — The project role of the project member. - `projectRoleName` (string, optional, nullable) — The project role name of the project member. - `isResponsible` (boolean, optional) — Whether the user is responsible for this project. - `isDeactivated` (boolean, optional) — Whether the user is deactivated. - `isExternal` (boolean, optional) — True if this entity is coming from an external workspace (awork Connect). ### CustomField Represents the custom field value. - `customFieldDefinitionId` (string, optional) — The custom field definition id. - `userIdValue` (string, optional, nullable) — The the user id value. - `clientIdValue` (string, optional, nullable) — The client id value. - `numberValue` (double, optional, nullable) — The number value. - `selectionOptionIdValue` (string, optional, nullable) — The selection option id value. - `selectionOption` (CustomFieldSelectionOption, optional) - `textValue` (string, optional, nullable) — The text value. - `dateValue` (string, optional, nullable) — The date value. - `booleanValue` (boolean, optional, nullable) — The boolean value. ### TeamModel - `id` (string, optional) — The id of the team. - `name` (string, optional, nullable) — The name of the team. - `icon` (string, optional, nullable) — The icon which is assigned to the team. - `color` (string, optional, nullable) — The color of the team. ### ValidationErrorResponse The validation error response. - `property` (string, optional, nullable) — The name of the property that failed validation. - `message` (string, optional, nullable) — The reason why this property failed validation. ### DefaultTagModel - `id` (string, optional) — The Id of the tag. - `name` (string, optional, nullable) — The name of the tag. - `color` (string, optional, nullable) — The color of the tag. - `entityId` (string, optional) — The id of the entity the tag is related to. ### CustomFieldSelectionOption - `value` (string, required) — The selection value which can be later used in a select custom field. - `id` (string, optional) — The id of the custom field selection option. - `color` (enum, optional, nullable) — The color of the selection option. - Allowed values: `red`, `orange`, `yellow`, `green`, `cyan`, `blue`, `indigo`, `purple`, `steel` - `order` (double, optional) — The order of the custom field selection option. ## Examples **Request** ```json { "workflowId": "123e4567-e89b-12d3-a456-426614174000" } ``` **Response** ```json { "name": "Website Design", "isPrivate": false, "description": "Sitemap, design, assets and implementation of the new online presence.", "startDate": "2022-03-01T00:00:00Z", "dueDate": "2022-05-01T00:00:00Z", "companyId": "123e4567-e89b-12d3-a456-426614174000", "timeBudget": 576000, "isBillableByDefault": true, "projectTypeId": "123e4567-e89b-12d3-a456-426614174000", "color": "purple", "deductNonBillableHours": true, "isProjectKeyVisible": true, "projectStatusId": "123e4567-e89b-12d3-a456-426614174000", "projectTemplateId": "123e4567-e89b-12d3-a456-426614174000", "publicProjectTemplateId": "123e4567-e89b-12d3-a456-426614174000", "workflowId": "123e4567-e89b-12d3-a456-426614174000", "id": "123e4567-e89b-12d3-a456-426614174000", "projectKey": "string", "hasImage": true, "createdOn": "2024-01-15T09:30:00Z", "createdBy": "123e4567-e89b-12d3-a456-426614174000", "updatedOn": "2024-01-15T09:30:00Z", "updatedBy": "123e4567-e89b-12d3-a456-426614174000", "closedOn": null, "closedBy": "123e4567-e89b-12d3-a456-426614174000", "createdByProjectTemplateId": "123e4567-e89b-12d3-a456-426614174000", "projectType": { "id": "80a2b26b-9fb3-42b5-b6dc-126c437cad5d", "name": "Design", "icon": "thumb_up", "isArchived": false }, "projectStatus": { "id": "80a2b26b-9fb3-42b5-b6dc-126c437cad5d", "name": "Design", "description": "Work in progress", "type": "todo", "isArchived": false, "typeOrder": 1, "isExternal": true }, "company": { "id": "80a2b26b-9fb3-42b5-b6dc-126c437cad5d", "name": "Design", "hasImage": true, "description": "A brand strategy and design agency", "tags": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Design", "color": "purple", "entityId": "123e4567-e89b-12d3-a456-426614174000" } ] }, "tags": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Design", "color": "purple" } ], "totalPlannedDurationWithHierarchy": 432000, "tasksCount": 12, "tasksDoneCount": 3, "members": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "userId": "123e4567-e89b-12d3-a456-426614174000", "firstName": "Lisa", "lastName": "Smith", "hasImage": true, "projectRoleId": "123e4567-e89b-12d3-a456-426614174000", "projectRoleName": "Project Manager", "isResponsible": true, "isDeactivated": false, "isExternal": true } ], "trackedDuration": 72000, "customFields": [ { "customFieldDefinitionId": "123e4567-e89b-12d3-a456-426614174000", "userIdValue": "123e4567-e89b-12d3-a456-426614174000", "clientIdValue": "123e4567-e89b-12d3-a456-426614174000", "numberValue": 123.45, "selectionOptionIdValue": "123e4567-e89b-12d3-a456-426614174000", "selectionOption": { "value": "Website Design", "id": "123e4567-e89b-12d3-a456-426614174000", "color": "purple", "order": 0 }, "textValue": "S1: Business Critical", "dateValue": "2024-01-15T09:30:00Z", "booleanValue": true } ], "resourceVersion": 637825154598057900, "teams": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Designers", "icon": "paintbrush", "color": "purple" } ], "isExternal": true, "isRetainer": true, "isMultiAssignmentAllowed": true, "plannedDuration": 432000 } ``` **SDK Code** ```python import requests url = "https://api.awork.com/api/v1/projects/projectId/linkworkflow" payload = { "workflowId": "123e4567-e89b-12d3-a456-426614174000" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.awork.com/api/v1/projects/projectId/linkworkflow'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"workflowId":"123e4567-e89b-12d3-a456-426614174000"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.awork.com/api/v1/projects/projectId/linkworkflow" payload := strings.NewReader("{\n \"workflowId\": \"123e4567-e89b-12d3-a456-426614174000\"\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 require 'uri' require 'net/http' url = URI("https://api.awork.com/api/v1/projects/projectId/linkworkflow") 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 \"workflowId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.awork.com/api/v1/projects/projectId/linkworkflow") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"workflowId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}") .asString(); ``` ```php request('POST', 'https://api.awork.com/api/v1/projects/projectId/linkworkflow', [ 'body' => '{ "workflowId": "123e4567-e89b-12d3-a456-426614174000" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.awork.com/api/v1/projects/projectId/linkworkflow"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"workflowId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["workflowId": "123e4567-e89b-12d3-a456-426614174000"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.awork.com/api/v1/projects/projectId/linkworkflow")! 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() ```