Creates or updates a single task in one call. Omit id to create a new task; pass the id of an existing task to update it. Responds 201 on create and 200 on update, with the full saved task as the body. The task's creator is always the API key's user; it cannot be set.

On create, name, status, and due_datetime are required. On update every field is optional: this is a sparse update, so only the fields you send are changed and any field you omit keeps its stored value. Sending a nullable optional field (description, color, owner_id, location_id) as null clears it; sending a required field as null is rejected with a 400.

Linking to another entity: set exactly one of order_id, invoice_id, purchase_id, contact_id, product_id, batch_id, assembly_id, return_id, or company_id. Sending more than one is a 400. The linked entity must exist in your company and be visible to the authenticated user; otherwise 400. The link is set-once: once a task is linked, the link cannot be changed or removed, and sending any relation field for an already-linked task is a 400. The linked entity is returned as in GET /public/v1/tasks.

Required permission: tasks_permissions_create to create, tasks_permissions_edit to update. Creating also requires the authenticated user's team restrictions to allow some access to tasks. Updating requires access to the task under those restrictions; a hidden task returns 403.

{
  "data": {
    "location": {
      "address": "1234 Warehouse Street, Oakland, CA",
      "company_id": "02c88a3f-d759-4973-88f9-60049d682524",
      "id": "02c88a3f-d759-4973-88f9-60049d682524",
      "license_id": "02c88a3f-d759-4973-88f9-60049d682524",
      "name": "Warehouse 1"
    }
  }
}