API REFERENCE

Update Project Task

On this page

PATCH/api/projects/{projectId}/tasks/{taskId}

Update a task. Send only the fields that change.

Completion is toggled with the completed boolean rather than by writing a timestamp: the server stamps completed_at and records completed_by from the authenticated account, so it is never ambiguous who closed an item. Any collaborator may toggle any task, including the client.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request PATCH \
  --url 'https://api.recoupable.dev/api/projects/YOUR_PROJECT_ID/tasks/YOUR_TASK_ID' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "completed": true
}'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Path parameters

projectIdstringrequired

The project's UUID.

taskIdstringrequired

The task's UUID.

Request body required

The fields to change.

application/json

titlestring

minLength: 1

descriptionstringnullable

due_datestringnullable

format: date

assignee_account_idstringnullable

format: uuid

completedboolean

true stamps completed_at with the current time and completed_by with the authenticated account. false clears both. This is the only way to change completion; completed_at is not writable directly.

Mark complete

markComplete

{
  "completed": true
}

Reopen

markIncomplete

{
  "completed": false
}

Change the due date

reschedule

{
  "due_date": "2026-09-19"
}

Responses

200Task updated.

application/json

statusstringrequired

taskobjectrequired

Properties

idstringrequired

format: uuid

project_idstringrequired

format: uuid

titlestringrequired

descriptionstringnullable

due_datestringnullable

A calendar date with no time of day, e.g. 2026-09-12.

format: date

assignee_account_idstringnullable

Who the task is waiting on. A client renders its "needs you" treatment when this matches the viewing account.

format: uuid

completed_atstringnullable

Null means the task is not complete. There is no separate boolean.

format: date-time

completed_bystringnullable

format: uuid

comment_countinteger

Number of comments on this task. Present on the project read so a list can render a count without a call per task.

format: int32

created_atstringrequired

Also the sort key: tasks come back oldest first.

format: date-time

updated_atstring

format: date-time

400Bad request — invalid path parameter or request body.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

messagestring

Carries the message in place of error when the failure comes from the authentication layer, so a 401 raised while verifying the credential reads message and every other error reads error.

401Unauthorized — missing or invalid credentials.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

messagestring

Carries the message in place of error when the failure comes from the authentication layer, so a 401 raised while verifying the credential reads message and every other error reads error.

404Not found — either no project or task with this id exists, or the authenticated account is not a collaborator on it. The two cases are deliberately indistinguishable so the response cannot be used to discover which project ids are real.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

messagestring

Carries the message in place of error when the failure comes from the authentication layer, so a 401 raised while verifying the credential reads message and every other error reads error.

500Internal server error.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

messagestring

Carries the message in place of error when the failure comes from the authentication layer, so a 401 raised while verifying the credential reads message and every other error reads error.

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download projects.json

View operation source

json

{
  "summary": "Update project task",
  "description": "Update a task. Send only the fields that change.\n\nCompletion is toggled with the `completed` boolean rather than by writing a timestamp: the server stamps `completed_at` and records `completed_by` from the authenticated account, so it is never ambiguous who closed an item. Any collaborator may toggle any task, including the client.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "projectId",
      "in": "path",
      "required": true,
      "description": "The project's UUID.",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "taskId",
      "in": "path",
      "required": true,
      "description": "The task's UUID.",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": {
    "description": "The fields to change.",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateProjectTaskRequest"
        },
        "examples": {
          "markComplete": {
            "summary": "Mark complete",
            "value": {
              "completed": true
            }
          },
          "markIncomplete": {
            "summary": "Reopen",
            "value": {
              "completed": false
            }
          },
          "reschedule": {
            "summary": "Change the due date",
            "value": {
              "due_date": "2026-09-19"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Task updated.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ProjectTaskMutationResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request — invalid path parameter or request body.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized — missing or invalid credentials.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Not found — either no project or task with this id exists, or the authenticated account is not a collaborator on it. The two cases are deliberately indistinguishable so the response cannot be used to discover which project ids are real.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}