> 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. # Updates the specified project retainer. PUT https://api.awork.com/api/v1/projects/{projectId}/retainers/{retainerId} Content-Type: application/json Updates the retainer settings. Date changes cannot overlap another retainer, and the retainer period cannot be changed. The user must have `project-master-data:write` permission for the project. Reference: https://developers.awork.com/apiv1/retainers/put-project-retainer-by-project-id-and-retainer-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 to update the retainer for. - `retainerId` (string, required) — The id of the retainer. ### Body (application/json) This endpoint expects a RetainerForm. - `timeBudget` (integer, optional) — The time budget per retainer period in seconds. The default budget amount for new budgets in this retainer. - `timezone` (string, optional, nullable) — The timezone for when new budgets are created. - `rollOverUnderspentBudget` (boolean, optional) — Whether underspent budgets should be rolled over to the next period. - `rollOverOverspentBudget` (boolean, optional) — Whether overspent budgets should be rolled over to the next period. - `startDate` (string, optional) — The start of the retainer contract. - `endDate` (string, optional, nullable) — The end of the retainer contract until new budgets will be created. Optional. - `syncProjectDates` (boolean, optional) — Whether the project start and due dates should be synced to the retainer start and end dates. ## Response ### 200 OK - `timeBudget` (integer, optional) — The time budget per retainer period in seconds. The default budget amount for new budgets in this retainer. - `timezone` (string, optional, nullable) — The timezone for when new budgets are created. - `rollOverUnderspentBudget` (boolean, optional) — Whether underspent budgets should be rolled over to the next period. - `rollOverOverspentBudget` (boolean, optional) — Whether overspent budgets should be rolled over to the next period. - `startDate` (string, optional) — The start of the retainer contract. - `endDate` (string, optional, nullable) — The end of the retainer contract until new budgets will be created. Optional. - `syncProjectDates` (boolean, optional) — Whether the project start and due dates should be synced to the retainer start and end dates. - `id` (string, optional) — The id of the retainer. - `retainerPeriod` (string, optional, nullable) — The period for new budgets in this retainer. Currently only 'monthly' is supported. - `projectId` (string, optional) — The project this retainer is associated with. - `isExternal` (boolean, optional) — Whether the retainer belongs to an external project. - `retainerBudgets` (list of RetainerBudget, optional, nullable) — The budgets for this retainer. Each budget period (month) gets its own budget. - `createdOn` (string, optional) — The date this retainer was created. - `createdBy` (string, optional) — The id of the user who created this retainer. - `updatedOn` (string, optional) — The date this retainer was last modified. - `updatedBy` (string, optional) — The id of the user who last modified this retainer. ## 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. ### 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 ### RetainerBudget - `id` (string, optional) — The id of the retainer budget. - `timeBudget` (integer, optional) — The budget for this retainer period in seconds. Based on the carry over option selected in the retainer settings, the timebudget is adjusted by the carry over from the previous period. - `trackedDuration` (integer, optional) — The sum of tracked time in this retainer period. Contains billable and non-billable hours if the DeductNonBillableHours flag is set to true. Contains only billable hours if the DeductNonBillableHours flag is set to false. Time entries belong to the retainer period if their StartDate is between the StartDate and EndDate of the retainer period. - `startDate` (string, optional) — The start of the retainer period in UTC. - `endDate` (string, optional) — The end of the retainer period in UTC. ### 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. ## Examples **Request** ```json {} ``` **Response** ```json { "timeBudget": 1, "timezone": "string", "rollOverUnderspentBudget": true, "rollOverOverspentBudget": true, "startDate": "2024-01-15T09:30:00Z", "endDate": "2024-01-15T09:30:00Z", "syncProjectDates": true, "id": "123e4567-e89b-12d3-a456-426614174000", "retainerPeriod": "string", "projectId": "123e4567-e89b-12d3-a456-426614174000", "isExternal": true, "retainerBudgets": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "timeBudget": 1, "trackedDuration": 1, "startDate": "2024-01-15T09:30:00Z", "endDate": "2024-01-15T09:30:00Z" } ], "createdOn": "2024-01-15T09:30:00Z", "createdBy": "123e4567-e89b-12d3-a456-426614174000", "updatedOn": "2024-01-15T09:30:00Z", "updatedBy": "123e4567-e89b-12d3-a456-426614174000" } ``` **SDK Code** ```python import requests url = "https://api.awork.com/api/v1/projects/projectId/retainers/retainerId" payload = {} headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.awork.com/api/v1/projects/projectId/retainers/retainerId'; const options = { method: 'PUT', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{}' }; 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/retainers/retainerId" payload := strings.NewReader("{}") req, _ := http.NewRequest("PUT", 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/retainers/retainerId") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.put("https://api.awork.com/api/v1/projects/projectId/retainers/retainerId") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('PUT', 'https://api.awork.com/api/v1/projects/projectId/retainers/retainerId', [ 'body' => '{}', '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/retainers/retainerId"); var request = new RestRequest(Method.PUT); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.awork.com/api/v1/projects/projectId/retainers/retainerId")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" 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() ```