## Update a task
**post** `/v1/tasks/{id}`
Updates an existing task by ID. Only included fields and relationships are modified.
The `$note` relationship is read-only — manage notes via their own relationships.
Supports idempotency via the `Idempotency-Key` header.
**[Required scope](/using-the-api/scopes/):** `tasks:update`
**[Rate limit category](/using-the-api/rate-limits/):** Write
### Path Parameters
- `id: string`
Unique identifier of the task to update.
### Body Parameters
- `fields: optional object { "$description", "$dueAt", "$status", "$title" }`
Field values to update — only provided fields are modified; omitted fields are left unchanged. Tasks only support the documented system fields, all prefixed with `$` (e.g. `$title`, `$status`). Call the [definitions endpoint](/api/resources/task/methods/definitions) for available fields. See [Fields and relationships](/using-the-api/fields-and-relationships/) for value type details.
- `"$description": optional string`
Description of the task in markdown format.
- `"$dueAt": optional string`
Due date as an ISO 8601 datetime string.
- `"$status": optional string`
Task status. One of: `TODO`, `IN_PROGRESS`, `COMPLETE`, `CANCELLED`.
- `"$title": optional string`
Title of the task.
- `relationships: optional object { "$account", "$assignedTo", "$opportunity" } or map[object { add, remove, replace } ]`
Relationship operations to apply. System relationships use a `$` prefix (e.g. `$account`, `$assignedTo`). Each value is an operation object with `add`, `remove`, or `replace`.
- `Typed object { "$account", "$assignedTo", "$opportunity" }`
- `"$account": optional object { add, remove, replace }`
Operation to modify the task account.
- `add: optional string or array of string`
Entity ID(s) to add to the relationship.
- `string`
- `array of string`
- `remove: optional string or array of string`
Entity ID(s) to remove from the relationship.
- `string`
- `array of string`
- `replace: optional string`
The entity ID to set as the relationship replacement, or null to clear supported relationships.
- `"$assignedTo": optional object { add, remove, replace }`
Operation to modify the assigned member.
- `add: optional string or array of string`
Entity ID(s) to add to the relationship.
- `string`
- `array of string`
- `remove: optional string or array of string`
Entity ID(s) to remove from the relationship.
- `string`
- `array of string`
- `replace: optional string`
The entity ID to set as the relationship replacement, or null to clear supported relationships.
- `"$opportunity": optional object { add, remove, replace }`
Operation to modify the associated opportunity.
- `add: optional string or array of string`
Entity ID(s) to add to the relationship.
- `string`
- `array of string`
- `remove: optional string or array of string`
Entity ID(s) to remove from the relationship.
- `string`
- `array of string`
- `replace: optional string`
The entity ID to set as the relationship replacement, or null to clear supported relationships.
- `Untyped = map[object { add, remove, replace } ]`
- `add: optional string or array of string`
Entity ID(s) to add to the relationship.
- `string`
- `array of string`
- `remove: optional string or array of string`
Entity ID(s) to remove from the relationship.
- `string`
- `array of string`
- `replace: optional string`
The entity ID to set as the relationship replacement, or null to clear supported relationships.
### Returns
- `TaskUpdateResponse object { id, createdAt, fields, 4 more }`
- `id: string`
Unique identifier for the entity.
- `createdAt: string`
ISO 8601 timestamp of when the entity was created.
- `fields: map[object { value, valueType } ]`
Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug.
- `value: string or number or boolean or 3 more`
The field value, or null if unset.
- `string`
- `number`
- `boolean`
- `array of string`
- `Address object { city, country, latitude, 5 more }`
- `city: optional string`
City name.
- `country: optional string`
2-letter ISO 3166-1 alpha-2 country code.
- `latitude: optional number`
Latitude coordinate.
- `longitude: optional number`
Longitude coordinate.
- `postalCode: optional string`
Postal or ZIP code.
- `state: optional string`
State or province.
- `street: optional string`
Street address line 1.
- `street2: optional string`
Street address line 2.
- `FullName object { firstName, lastName }`
- `firstName: optional string`
The contact's first name.
- `lastName: optional string`
The contact's last name.
- `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more`
The data type of the field.
- `"ADDRESS"`
- `"CHECKBOX"`
- `"CURRENCY"`
- `"DATETIME"`
- `"EMAIL"`
- `"FULL_NAME"`
- `"MARKDOWN"`
- `"MULTI_SELECT"`
- `"NUMBER"`
- `"SINGLE_SELECT"`
- `"SOCIAL_HANDLE"`
- `"TELEPHONE"`
- `"TEXT"`
- `"URL"`
- `"HTML"`
- `httpLink: string`
URL to view the entity in the Lightfield web app, or null.
- `relationships: map[object { cardinality, objectType, values, directions } ]`
Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). A self-referential relationship keeps its merged values and includes optional directional values. List filters select the current record's role with `:asSource` or `:asDestination`, for example `?parent:asSource[contains]=account_id`.
- `cardinality: string`
Whether the relationship is `has_one` or `has_many`.
- `objectType: string`
The type of the related object (e.g. `account`, `contact`).
- `values: array of string`
IDs of the related entities.
- `directions: optional object { asDestination, asSource }`
Directional values for a self-referential relationship. List filters use the relationship key with `:asSource` or `:asDestination`; writes continue to use the bare key.
- `asDestination: object { cardinality, values }`
The current record is the destination (incoming) endpoint.
- `cardinality: "HAS_ONE" or "HAS_MANY"`
Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`.
- `"HAS_ONE"`
- `"HAS_MANY"`
- `values: array of string`
IDs of the related entities in this direction.
- `asSource: object { cardinality, values }`
The current record is the source (outgoing) endpoint.
- `cardinality: "HAS_ONE" or "HAS_MANY"`
Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`.
- `"HAS_ONE"`
- `"HAS_MANY"`
- `values: array of string`
IDs of the related entities in this direction.
- `updatedAt: string`
ISO 8601 timestamp of when the entity was last updated, or null.
- `externalId: optional string`
External identifier for the entity, or null if unset.
### Example
```http
curl https://api.lightfield.app/v1/tasks/$ID \
-H 'Content-Type: application/json' \
-H 'Lightfield-Version: 2026-03-01' \
-H "Authorization: Bearer $API_KEY" \
-d '{}'
```
#### Response
```json
{
"id": "id",
"createdAt": "createdAt",
"fields": {
"foo": {
"value": "string",
"valueType": "ADDRESS"
}
},
"httpLink": "httpLink",
"relationships": {
"foo": {
"cardinality": "cardinality",
"objectType": "objectType",
"values": [
"string"
],
"directions": {
"asDestination": {
"cardinality": "HAS_ONE",
"values": [
"string"
]
},
"asSource": {
"cardinality": "HAS_ONE",
"values": [
"string"
]
}
}
}
},
"updatedAt": "updatedAt",
"externalId": "externalId"
}
```