---
title: "Update task metadata"
method: PUT
path: "/v2/tasks/{task_id}/update_metadata"
tags: ["tasks"]
---

# Update task metadata

`PUT /v2/tasks/{task_id}/update_metadata`

## Request

- Base URL: `https://api.hubstaff.com`
- URL: `https://api.hubstaff.com/v2/tasks/{task_id}/update_metadata`
- Auth: OAuth 2
  - Authorization code: `https://account.hubstaff.com/authorizations/new`
  - Token URL: `https://account.hubstaff.com/access_tokens` scopes: `hubstaff:read`, `hubstaff:write`
- TypeScript: <https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/docs/v2/tasks/:task_id/update_metadata/put.ts> (a function with typed inputs; its response is checked against the schema)

Updates metadata on the task.

Returns the updated task.

Only specify the metadata keys you want to change. If the metadata key does not exist, it will be created. To remove a key, specify null as the value. Requires passing lock_version from the task fetch.

Key requirements:
- 2-30 characters
- Lowercase letters, numbers, and underscores only

Value requirements:
- Valid UTF-8 string
- Maximum 200 characters

## Path parameters

- `task_id` integer, required

## Request body

- PutV2TasksTaskIdUpdateMetadata: Update task metadata
  - `lock_version` integer, required: Lock version
  - `metadata` object[], required
    - `key` string, required: The metadata key
    - `value` string, required: The value for the metadata key

## Response `200`

A client

- object
  - `task` Task: Task model
    - `id` integer, required: Task id
    - `integration_id` integer: Integration ID
    - `status` string, required: Task status
    - `project_id` integer, required: Project ID
    - `project_type` string, required: Project type
    - `summary` string, required: Task summary
    - `details` string: Task details
    - `remote_id` string: Remote ID of the task in the external system
    - `remote_alternate_id` string: Alternate Remote ID of the task in the external system
    - `lock_version` integer: lock version
    - `assignee_ids` integer[], required: Assignee user IDs for this task
    - `pay_rate` number, float: Task pay rate
    - `bill_rate` number, float: Task bill rate
    - `metadata` object, required: Metadata attached to the task
    - `completed_at` string, date-time: Date and time task was completed
    - `due_at` string, date-time: Date and time task is due
    - `created_at` string, date-time, required: Date and time task was created
    - `updated_at` string, date-time, required: Date and time task was last updated
    - `global_todo_id` integer: Global To-Do ID

## Other responses

- `400`: Invalid parameters
- `401`: Unauthorized
- `403`: API access is only for organizations on an active plan
- `404`: Could not find record
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api.md) - [All operations](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/revisions/c6b90e4e4bdc?raw)