Remove task from time entry when project changes without a new task

PUT /time-entries/{id} accepted a new project_id while keeping a task from
the previous project, leaving the entry with a task that belongs to a
different project. The bulk endpoint already handled a project switch but
kept the task when the project was removed.

Both endpoints now remove the task whenever project_id is changed without
task_id and the current task does not belong to the new project.

app/Http/Controllers/Api/V1/InvitationController.php

@@ -88,8 +88,6 @@ class InvitationController extends Controller
     /**
      * Remove a pending invitation
      *
-     * This revokes the invitation: the link in the invitation email stops working. Find the invitation ID with `GET /organizations/{organization}/invitations`.
-     *
      * @throws AuthorizationException
      *
      * @operationId removeInvitation

app/Http/Controllers/Api/V1/MemberController.php

@@ -145,9 +145,6 @@ class MemberController extends Controller
     /**
      * Merge one member into another
      *
-     * Only placeholder members (for example people created by an import) can be merged. All time entries and other data of the placeholder
-     * are reassigned to the member given in `member_id`, and the placeholder is removed. Find both member IDs with `GET /organizations/{organization}/members`.
-     *
      * @throws AuthorizationException
      * @throws OnlyPlaceholdersCanBeMergedIntoAnotherMember
      * @throws Throwable

app/Http/Controllers/Api/V1/ReportController.php

@@ -71,8 +71,6 @@ class ReportController extends Controller
     /**
      * Create report
      *
-     * A report is a saved set of filters. Set `is_public` to `true` to share it: the response then contains the `shareable_link` that can be opened without logging in.
-     *
      * @throws AuthorizationException
      *
      * @operationId createReport

app/Http/Controllers/Api/V1/TimeEntryController.php

@@ -109,14 +109,9 @@ class TimeEntryController extends Controller
     /**
      * Get time entries in organization
      *
-     * Without a member filter this returns the time entries of all members of the organization (for users who may view all time entries, such as owners and admins), not only your own.
-     * To get only your own time entries, pass your member ID as `member_id`. Your member ID is the `id` returned for this organization by `GET /v1/users/me/memberships`; it is not your user ID.
+     * If you only need time entries for a specific user, you can filter by `member_id`.
      * Users with the permission `time-entries:view:own` can only use this endpoint with their own member ID in the member_id filter.
      *
-     * The `start` and `end` filters both apply to the start time of an entry, in UTC. Convert the user's local day boundaries to UTC first.
-     * Results are paginated with `limit` (default 100, max 500) and `offset`; check `meta.total` and fetch further pages when needed.
-     * To find the running timer, use `active=true` (or `GET /v1/users/me/time-entries/active`).
-     *
      * @return TimeEntryCollection<TimeEntryResource>
      *
      * @throws AuthorizationException
@@ -356,11 +351,6 @@ class TimeEntryController extends Controller
      * The parameters `group` and `sub_group` allow you to group the time entries by different criteria.
      * If the group parameters are all set to `null` or are all missing, the endpoint will aggregate all filtered time entries.
      *
-     * Durations are returned in `seconds` (divide by 3600 for hours) and amounts in `cost` as cents in the organization's currency (divide by 100 for money).
-     * Filter by member with `member_id`. Your member ID is the `id` returned for this organization by `GET /v1/users/me/memberships`; it is not your user ID.
-     * Array filters use the query format `client_ids[]=<id>`.
-     * Example: billable hours per client for a period: `group=client&billable=true&start=...&end=...`.
-     *
      * @operationId getAggregatedTimeEntries
      *
      * @return array{
@@ -594,12 +584,6 @@ class TimeEntryController extends Controller
     /**
      * Create time entry
      *
-     * `billable` is not taken from the project. To match the web app, set it to the project's `is_billable` value (or `false` without a project).
-     *
-     * A member can only have one running time entry (an entry with `end` set to `null`). Creating a running entry while another one runs fails with `time_entry_still_running`.
-     * To start a new timer, first stop the running entry by updating its `end` to the current time, then create the new entry.
-     * To log past work, send both `start` and `end` (UTC). Create one entry per block of work.
-     *
      * @throws AuthorizationException
      * @throws TimeEntryStillRunningApiException
      *
@@ -650,8 +634,6 @@ class TimeEntryController extends Controller
     /**
      * Update time entry
      *
-     * To stop a running timer, set `end` to the stop time (UTC). Times the user gives in their own timezone must be converted to UTC first.
-     *
      * @throws AuthorizationException|TimeEntryCanNotBeRestartedApiException
      *
      * @operationId updateTimeEntry
@@ -697,6 +679,10 @@ class TimeEntryController extends Controller
             $timeEntry->member()->associate($newMember);
             $timeEntry->user()->associate($newMember->user);
         }
+        // If project is changed, but task is not, we remove the old task from the time entry
+        if ($request->has('project_id') && ! $request->has('task_id') && $oldTask !== null && $oldTask->project_id !== $project?->getKey()) {
+            $timeEntry->task()->disassociate();
+        }
         $timeEntry->description = $request->input('description', $timeEntry->description) ?? '';
         $timeEntry->setComputedAttributeValue('billable_rate');
         $timeEntry->save();
@@ -720,10 +706,6 @@ class TimeEntryController extends Controller
     /**
      * Update multiple time entries
      *
-     * Applies the same `changes` to every entry in `ids`. To find the IDs, list entries with `GET /organizations/{organization}/time-entries`
-     * (filtered by `member_id`, the project and the other criteria), then send their IDs here.
-     * When `changes.project_id` moves entries to another project, also set `changes.task_id` to a task of the new project or to `null`, because tasks belong to a project.
-     *
      * @operationId updateMultipleTimeEntries
      *
      * @throws AuthorizationException
@@ -812,7 +794,7 @@ class TimeEntryController extends Controller
                 $timeEntry->user_id = $newMember->user_id;
             }
             // If project is changed, but task is not, we remove the old task from the time entry
-            if ($oldProject !== null && $project !== null && $oldProject->isNot($project) && $task === null) {
+            if ($request->has('changes.project_id') && ! $request->has('changes.task_id') && $oldTask !== null && $oldTask->project_id !== $project?->getKey()) {
                 $timeEntry->task()->disassociate();
             }
             if ($overwriteClient) {

app/Http/Requests/V1/Member/MemberUpdateRequest.php

@@ -27,7 +27,6 @@ class MemberUpdateRequest extends BaseFormRequest
                 'string',
                 Rule::enum(Role::class),
             ],
-            // Billable rate in cents per hour (example: 8000 means 80.00 in the organization's currency)
             'billable_rate' => array_merge(
                 [
                     'nullable',

app/Http/Requests/V1/Organization/OrganizationUpdateRequest.php

@@ -36,7 +36,6 @@ class OrganizationUpdateRequest extends BaseFormRequest
                 'string',
                 new CurrencyRule,
             ],
-            // Billable rate in cents per hour (example: 8000 means 80.00 in the organization's currency)
             'billable_rate' => array_merge(
                 [
                     'nullable',

app/Http/Requests/V1/Project/ProjectStoreRequest.php

@@ -55,7 +55,6 @@ class ProjectStoreRequest extends BaseFormRequest
                 'required',
                 'boolean',
             ],
-            // Billable rate in cents per hour (example: 8000 means 80.00 in the organization's currency)
             'billable_rate' => array_merge(
                 [
                     'nullable',

app/Http/Requests/V1/Project/ProjectUpdateRequest.php

@@ -68,7 +68,6 @@ class ProjectUpdateRequest extends BaseFormRequest
                     return $builder->whereBelongsTo($this->organization, 'organization');
                 })->uuid(),
             ],
-            // Billable rate in cents per hour (example: 8000 means 80.00 in the organization's currency)
             'billable_rate' => array_merge([
                 'nullable',
             ],

app/Http/Requests/V1/ProjectMember/ProjectMemberStoreRequest.php

@@ -31,7 +31,6 @@ class ProjectMemberStoreRequest extends BaseFormRequest
                     return $builder->whereBelongsTo($this->organization, 'organization');
                 })->uuid(),
             ],
-            // Billable rate in cents per hour (example: 8000 means 80.00 in the organization's currency)
             'billable_rate' => array_merge(
                 [
                     'nullable',

app/Http/Requests/V1/ProjectMember/ProjectMemberUpdateRequest.php

@@ -21,7 +21,6 @@ class ProjectMemberUpdateRequest extends BaseFormRequest
     public function rules(): array
     {
         return [
-            // Billable rate in cents per hour (example: 8000 means 80.00 in the organization's currency)
             'billable_rate' => array_merge(
                 [
                     'nullable',

app/Http/Requests/V1/TimeEntry/TimeEntryIndexRequest.php

@@ -35,7 +35,7 @@ class TimeEntryIndexRequest extends BaseFormRequest
     public function rules(): array
     {
         return [
-            // Filter by member ID. Without it, users who may view all time entries (owners, admins) get the entries of every member; pass your own member ID (from GET /v1/users/me/memberships) to get only yours
+            // Filter by member ID
             'member_id' => [
                 'string',
                 ExistsEloquent::make(Member::class, null, function (Builder $builder): Builder {
@@ -155,7 +155,7 @@ class TimeEntryIndexRequest extends BaseFormRequest
                 'string',
                 Rule::enum(TimeEntryType::class),
             ],
-            // Limit the number of returned time entries (default: 100)
+            // Limit the number of returned time entries (default: 150)
             'limit' => [
                 'integer',
                 'min:1',

app/Http/Requests/V1/TimeEntry/TimeEntryStoreRequest.php

@@ -32,7 +32,7 @@ class TimeEntryStoreRequest extends BaseFormRequest
     public function rules(): array
     {
         return [
-            // ID of the organization member that the time entry should belong to (a member ID from GET /v1/users/me/memberships or the members list, not a user ID)
+            // ID of the organization member that the time entry should belong to
             'member_id' => [
                 'required',
                 'string',
@@ -86,7 +86,7 @@ class TimeEntryStoreRequest extends BaseFormRequest
                 'date_format:Y-m-d\TH:i:s\Z',
                 'after_or_equal:start',
             ],
-            // Whether time entry is billable. Not derived from the project: set it to the project's is_billable value to match the web app
+            // Whether time entry is billable
             'billable' => [
                 'required',
                 'boolean',

config/scramble.php

@@ -28,30 +28,7 @@ return [
         /*
          * Description rendered on the home page of the API documentation (`/docs/api`).
          */
-        'description' => <<<'MD'
-## Getting started
-
-All organization endpoints live under `/v1/organizations/{organization}`, where `{organization}` is the organization's ID. Authenticate with `Authorization: Bearer <token>` and send `Accept: application/json`.
-
-**1. Find yourself.** Call `GET /v1/users/me/memberships`. Each membership contains the **organization ID** (use it as `{organization}` in paths) and your **member ID** in that organization (the membership `id`). Most endpoints filter by member ID, not by user ID.
-
-**2. Scope to your own data.** For owners and admins, `GET /time-entries` and `GET /time-entries/aggregate` return the whole organization's time entries unless you pass `member_id`. When acting for "me", always pass your member ID, both when reading and before changing entries.
-
-**3. Resolve names to IDs.** Look up projects, clients, tags, tasks and members by name with their list endpoints (`GET /projects`, `GET /clients`, `GET /tags`, `GET /tasks`, `GET /members`). Never guess IDs.
-
-**4. Use UTC.** All timestamps are sent and returned in UTC as `Y-m-d\TH:i:s\Z` (example: `2026-10-02T07:30:00Z`). Convert the user's local times and day boundaries to UTC before sending them.
-
-**5. Money is in cents.** Billable rates and costs are integers in cents of the organization's currency (`8000` means 80.00).
-
-## Common tasks
-
-- **Start a timer:** stop the running entry first (find it with `GET /v1/users/me/time-entries/active`, then `PUT` its `end`), then `POST /time-entries` with `start` and `end: null`. Only one entry can run per member.
-- **Log past work:** `POST /time-entries` once per block with `member_id`, `start`, `end`, `project_id` and `billable` set to the project's `is_billable` (it is not derived automatically).
-- **Fix or stop an entry:** `PUT /time-entries/{timeEntry}` with the new `start` or `end` in UTC.
-- **Move entries to another project:** list them with `member_id` and filters, then `PATCH /time-entries` with their `ids` and `changes.project_id`, plus `changes.task_id` set to a task of the new project or `null`.
-- **Totals and reports:** `GET /time-entries/aggregate` with `group` (for example `client` or `project`) and `start`/`end`; durations are in `seconds`, amounts in `cost` (cents).
-- **Share a report:** `POST /reports` with `is_public: true` and use the returned `shareable_link`.
-MD,
+        'description' => '',
     ],
 
     /*

tests/Unit/Endpoint/Api/V1/TimeEntryEndpointTest.php

@@ -2780,6 +2780,90 @@ class TimeEntryEndpointTest extends ApiEndpointTestAbstract
         });
     }
 
+    public function test_update_endpoint_removes_task_if_project_is_changed_without_setting_a_new_task(): void
+    {
+        // Arrange
+        $data = $this->createUserWithPermission([
+            'time-entries:update:own',
+            'projects:view:all',
+        ]);
+        $project1 = Project::factory()->forOrganization($data->organization)->create();
+        $project2 = Project::factory()->forOrganization($data->organization)->create();
+        $task1 = Task::factory()->forProject($project1)->forOrganization($data->organization)->create();
+        $timeEntry = TimeEntry::factory()->forOrganization($data->organization)->forProject($project1)->forTask($task1)->forMember($data->member)->create();
+        Passport::actingAs($data->user);
+
+        // Act
+        $response = $this->putJson(route('api.v1.time-entries.update', [$data->organization->getKey(), $timeEntry->getKey()]), [
+            'project_id' => $project2->getKey(),
+        ]);
+
+        // Assert
+        $response->assertValid();
+        $this->assertResponseCode($response, 200);
+        $response->assertJsonPath('data.project_id', $project2->getKey());
+        $response->assertJsonPath('data.task_id', null);
+        $this->assertDatabaseHas(TimeEntry::class, [
+            'id' => $timeEntry->getKey(),
+            'project_id' => $project2->getKey(),
+            'task_id' => null,
+        ]);
+    }
+
+    public function test_update_endpoint_removes_task_if_project_is_removed_without_removing_the_task(): void
+    {
+        // Arrange
+        $data = $this->createUserWithPermission([
+            'time-entries:update:own',
+            'projects:view:all',
+        ]);
+        $project = Project::factory()->forOrganization($data->organization)->create();
+        $task = Task::factory()->forProject($project)->forOrganization($data->organization)->create();
+        $timeEntry = TimeEntry::factory()->forOrganization($data->organization)->forProject($project)->forTask($task)->forMember($data->member)->create();
+        Passport::actingAs($data->user);
+
+        // Act
+        $response = $this->putJson(route('api.v1.time-entries.update', [$data->organization->getKey(), $timeEntry->getKey()]), [
+            'project_id' => null,
+        ]);
+
+        // Assert
+        $response->assertValid();
+        $this->assertResponseCode($response, 200);
+        $this->assertDatabaseHas(TimeEntry::class, [
+            'id' => $timeEntry->getKey(),
+            'project_id' => null,
+            'task_id' => null,
+        ]);
+    }
+
+    public function test_update_endpoint_keeps_task_if_project_is_set_to_the_project_of_the_task(): void
+    {
+        // Arrange
+        $data = $this->createUserWithPermission([
+            'time-entries:update:own',
+            'projects:view:all',
+        ]);
+        $project = Project::factory()->forOrganization($data->organization)->create();
+        $task = Task::factory()->forProject($project)->forOrganization($data->organization)->create();
+        $timeEntry = TimeEntry::factory()->forOrganization($data->organization)->forProject($project)->forTask($task)->forMember($data->member)->create();
+        Passport::actingAs($data->user);
+
+        // Act
+        $response = $this->putJson(route('api.v1.time-entries.update', [$data->organization->getKey(), $timeEntry->getKey()]), [
+            'project_id' => $project->getKey(),
+        ]);
+
+        // Assert
+        $response->assertValid();
+        $this->assertResponseCode($response, 200);
+        $this->assertDatabaseHas(TimeEntry::class, [
+            'id' => $timeEntry->getKey(),
+            'project_id' => $project->getKey(),
+            'task_id' => $task->getKey(),
+        ]);
+    }
+
     public function test_update_endpoint_fails_if_employee_tries_to_update_time_entry_to_private_project_without_access(): void
     {
         // Arrange
@@ -3807,6 +3891,44 @@ class TimeEntryEndpointTest extends ApiEndpointTestAbstract
         ]);
     }
 
+    public function test_update_multiple_removes_task_from_time_entries_if_project_is_removed_without_removing_the_task(): void
+    {
+        // Arrange
+        $data = $this->createUserWithPermission([
+            'time-entries:update:own',
+            'projects:view:all',
+        ]);
+        $project = Project::factory()->forOrganization($data->organization)->create();
+        $task = Task::factory()->forProject($project)->forOrganization($data->organization)->create();
+        $timeEntry = TimeEntry::factory()->forOrganization($data->organization)->forProject($project)->forTask($task)->forMember($data->member)->create();
+        Passport::actingAs($data->user);
+
+        // Act
+        $response = $this->patchJson(route('api.v1.time-entries.update-multiple', [$data->organization->getKey()]), [
+            'ids' => [
+                $timeEntry->getKey(),
+            ],
+            'changes' => [
+                'project_id' => null,
+            ],
+        ]);
+
+        // Assert
+        $response->assertValid();
+        $this->assertResponseCode($response, 200);
+        $response->assertExactJson([
+            'success' => [
+                $timeEntry->getKey(),
+            ],
+            'error' => [],
+        ]);
+        $this->assertDatabaseHas(TimeEntry::class, [
+            'id' => $timeEntry->getKey(),
+            'project_id' => null,
+            'task_id' => null,
+        ]);
+    }
+
     public function test_update_multiple_updates_own_time_entries_and_fails_for_time_entries_of_other_users_and_and_other_organizations_with_own_time_entries_permission(): void
     {
         // Arrange