submit_timesheet
Puts a week of time on a project to its approver as the person the token acts as, opening the week's timesheet when it has none, with optional words for the approver; the week's logs hold from then on.
Put a week forward when the person asks for it to go in. Give project_id and week_start (any day of the week, Y-m-d; the week runs Monday to Sunday), a summary for the approver when the week needs a word, and user_id to put another member's week forward when the token's holder may approve time on the project. The tool opens the week's timesheet when none exists yet, tallies its logs as they stand, and opens the approval request the project's Timesheet approval policy names; when the approver asked for changes, it opens the next round instead. The answer carries both the approval request and the timesheet. From that moment the week's logs on that project hold until the approver answers or the week is withdrawn; an approval locks them. Never put a week forward on your own initiative: the person says when their week is complete.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Arguments
project_id*stringUUID of the project the week belongs to.
week_start*stringAny day of the week to put forward, Y-m-d; the week runs Monday to Sunday.
user_idstringoptionalWhose week, when not the person the token acts as; needs the right to approve time on the project.
summarystringoptionalWords for the approver, up to 2000 characters.
What it returns
{ "data": { "approval": { "id": "9c8b7a6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "approvable_type": "timesheet", "approvable_id": "4a5b6c7d-8e9f-4a1b-8c2d-3e4f5a6b7c8d", "reference": "Week of Nov 2, 2026", "title": "Dev Lead, Week of Nov 2, 2026: 38h logged", "kind": "timesheet_approval", "status": "pending", "rule": "any", "quorum": 1, "round": 1, "summary": "Two days on the tier job, one on the receipt bug.", "requested_by": "3f8a1c2e-7b4d-4e5f-9a6b-1c2d3e4f5a6b", "due_at": "2026-11-11T17:30:00+00:00" }, "timesheet": { "id": "4a5b6c7d-8e9f-4a1b-8c2d-3e4f5a6b7c8d", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "project_key": "CRM", "user_id": "3f8a1c2e-7b4d-4e5f-9a6b-1c2d3e4f5a6b", "week_start": "2026-11-02", "week_end": "2026-11-08", "status": "submitted", "held": true, "total_minutes": 2280, "total_duration": "38h", "billable_minutes": 1800, "entry_count": 12, "submitted_at": "2026-11-08T17:30:00+00:00", "version": 0 } }}How it fails
VALIDATION_FAILEDweek_start missing or malformed, a week with no time on it, a week already awaiting approval or approved, or a project with nobody named to approve timesheets.
RESOURCE_NOT_FOUNDunknown project_id, or a project outside the token's scope.
FORBIDDENthe holder may not log time on the project, names someone else without time-log:approve, or the token is a client guest's.
TOKEN_MISSING_ABILITYtoken lacks time-log:create.
How is this guide?
Last updated on