Update a task

Update an existing task in the workspace.

PATCH /v1/tasks/{taskId}

Update a task

cURL

curl --request PATCH \
  --url https://api.folk.app/v1/tasks/{taskId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Follow up with John Doe",
  "dueAt": "2025-07-17",
  "dueTime": "15:00",
  "description": "Discuss the Q3 proposal.",
  "assignedUsers": [
    {
      "id": "<string>",
      "email": "<string>"
    }
  ],
  "isPublic": true,
  "entity": {
    "id": "per_55175e81-9a52-4ac3-930e-82792c23499b"
  }
}
'

200

{
  "data": {
    "id": "tsk_91118b73-5a75-480b-b8e3-a33671c35cdc",
    "title": "Follow up with John Doe",
    "description": "Discuss the Q3 proposal.",
    "entity": {
      "id": "per_55175e81-9a52-4ac3-930e-82792c23499b",
      "entityType": "person",
      "fullName": "John Doe"
    },
    "dueAt": "2025-07-17",
    "dueTime": "15:00",
    "completedAt": null,
    "recurrenceFrequency": null,
    "isPublic": true,
    "assignedUsers": [
      {
        "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
        "fullName": "John Doe",
        "email": "[e-mail]"
      }
    ],
    "createdBy": {
      "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
      "fullName": "John Doe",
      "email": "[e-mail]"
    },
    "createdAt": "2025-07-17T09:00:00.000Z",
    "updatedAt": "2025-07-17T09:00:00.000Z"
  }
}

Update an existing task, updating only the provided fields and leaving the rest of the task’s data unchanged.

To move a task to a different entity, provide a new entity.id. Omit entity entirely to keep the task on its current entity.

This endpoint does not change completedAt — use Mark a task as done or Mark a task as to do to change completion state.

Authorizations

Authorization · string · header · required

API key for authentication

Headers

Idempotency-Key · string

A unique key, such as a UUID, that makes retrying this request safe: a retry with the same key and body returns the original response without running the operation again. Keys are kept for 24 hours after the request completes.

Maximum string length: 255

Example:

"8e03978e-40d5-43e8-bc93-6894a57f9324"

Path Parameters

taskId · string · required

The ID of the task to update.

Required string length: 40

Body

application/json

title · string

The title of the task.

Maximum string length: 255

Example:

"Follow up with John Doe"

dueAt · string<date>

The due date of the task, in YYYY-MM-DD format.

Required string length: 10

Example:

"2025-07-17"

dueTime · string | null

The due time of the task, in HH:mm format.

Required string length: 5

Example:

"15:00"

description · string | null

The description of the task, in markdown format.

Maximum string length: 10000

Example:

"Discuss the Q3 proposal."

recurrenceFrequency · enum<string> | null

The recurrence frequency of the task. One of: weekday, weekly, biweekly, monthly, quarterly, yearly. Null if non-recurring.

Available options: weekday, weekly, biweekly, monthly, quarterly, yearly, null

assignedUsers · object[]

Users to assign to this task. Accepts user IDs or emails, not both. If omitted, the task is assigned to the current user (the API key owner).

Maximum array length: 50

Show child attributes

isPublic · boolean

Whether the task is visible to all workspace members (true) or only to its assigned users (false).

Example:

true

entity · object

The entity to move the task to. Omit to keep the current entity. You can link people, companies and deals.

Show child attributes

Example:

{
  "id": "per_55175e81-9a52-4ac3-930e-82792c23499b"
}

Response

200

application/json

The task updated in the workspace.

data · object · required

A task created by a user.

Show child attributes

Example:

{
  "id": "tsk_91118b73-5a75-480b-b8e3-a33671c35cdc",
  "title": "Follow up with John Doe",
  "description": "Discuss the Q3 proposal.",
  "entity": {
    "id": "per_55175e81-9a52-4ac3-930e-82792c23499b",
    "entityType": "person",
    "fullName": "John Doe"
  },
  "dueAt": "2025-07-17",
  "dueTime": "15:00",
  "completedAt": null,
  "recurrenceFrequency": null,
  "isPublic": true,
  "assignedUsers": [
    {
      "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
      "fullName": "John Doe",
      "email": "[e-mail]"
    }
  ],
  "createdBy": {
    "id": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
    "fullName": "John Doe",
    "email": "[e-mail]"
  },
  "createdAt": "2025-07-17T09:00:00.000Z",
  "updatedAt": "2025-07-17T09:00:00.000Z"
}

deprecations · string[]

Example:

["This field is deprecated"]