Project and time tools

For: developers connecting an HTTP or MCP client. Start with Connect your client.

The project tools use the delegated person's current permissions. The scope identifiers remain engagements:read and engagements:prepare; the interface calls this module Projects. Tool identifiers remain stable when a product label changes.

Tasks and time

MCP tool	HTTP path after `/api/v1/`	Scope	Result
`tasks_list`	`GET tasks`	`engagements:read`	Permitted tasks with keys, status, assignee, dates and estimates
`tasks_get`	`GET tasks/{id}`	`engagements:read`	One task with checklist, dependencies, permitted logged minutes and current version
`tasks_create`	`POST tasks`	`engagements:prepare`	A task with its next project or standalone key
`tasks_update`	`POST tasks/{id}`	`engagements:prepare`	A task edited at its current version
`tasks_complete`	`POST tasks/{id}/complete`	`engagements:prepare`	A task moved to its completed status
`time_list`	`GET time`	`engagements:read`	Permitted settled entries with exact minutes and allocation state
`time_log`	`POST time`	`engagements:prepare`	A saved entry with exact minutes and resolved rates
`time_start`	`POST time/start`	`engagements:prepare`	The person's running timer; any previous timer stops first
`time_stop`	`POST time/stop`	`engagements:prepare`	The stopped entry, or null when no timer runs
`time_pause`	`POST time/pause`	`engagements:prepare`	The paused entry with the time so far; the work stays ready to resume
`time_resume`	`POST time/resume`	`engagements:prepare`	A new running entry on the paused task and project
`time_dismiss`	`POST time/dismiss`	`engagements:prepare`	The paused entry, now cleared from the timer, or null
`projects_unbilled`	`GET projects/unbilled`	`engagements:read`	Unbilled time and value by project, customer and person
`projects_margin`	`GET projects/margin`	`engagements:read`	Invoiced, purchases, costed time and margin per project
`projects_workload`	`GET projects/workload`	`engagements:read`	Available, planned and logged time per person and day
`views_task`	`GET views/task`	`engagements:read`	A scoped task view with filters, sorting and grouping

Task and time tools require Use projects or Manage projects. Financial tools require View financial summaries. Workload requires Manage projects. Granting a connection scope never grants those business permissions.

Employees read tasks they created or tasks assigned to them or their active teams. They read their own time and billing rate. Managers can read other people's entries. Guests need an explicit project grant and receive no rates, cost rates or margin. Lists and linked-card facts do not disclose rates. A record outside scope returns 404 without its details.

Inputs

Task lists accept limit (25, 50 or 100), cursor, sort (due_on, priority, created_at or title), dir, search, project_id and view (open, mine, overdue, done, all). The default view is open.

Task creation requires title (up to 240 characters). Optional fields are project_id, description, status_id, assignee, starts_on, due_on, priority, estimate_minutes and tags. Without a project, it creates a standalone task. Priority runs from 1 (urgent) through 4 (low), with 3 as the default. Use user:<id> or team:<id> for an assignee; employees may choose themselves or a team they belong to. Read project statuses through engagements_get.

Task updates require id and the current version from tasks_get. They accept the editable fields above except project_id and status_id. tasks_complete also needs id and version. To reopen a task, move it to another status, move it into a project or change its dependencies, use the tools in Everyday changes.

Time logging requires minutes between 1 and 1,440 and either task_id or project_id. Optional fields are entry_date, note (up to 500 characters), billable and user_id. The business date defaults to today; the billing mode supplies the billable default. user_id defaults to the delegated person. Recording another person's time requires Manage projects.

Timer start needs a task or project. Timer stop, pause, resume and dismiss take no business input. Pause refuses with 422 when no timer runs. Resume refuses with 422 when nothing is paused, or when the paused task is archived, its project is closed or the person can no longer open it. Time lists accept limit, cursor, sort (entry_date, minutes or created_at), dir, search, from, to, project_id and task_id.

Unbilled accepts project_id or customer_id. Margin accepts project_id. Workload accepts week, any YYYY-MM-DD date of the week; the week starts on Monday. Amounts stay exact minor-unit strings with a currency and scale. Each report uses the same figures as its screen and CSV export.

Every write requires an idempotency_key. Retry an uncertain response with the same key and input. A changed input needs a new key. For a stale version, read the task again, review it and retry with a new key.

Everyday changes

These tools make the changes that a person makes on My work, the task and project pages, the timesheet and the project settings. Each one runs the same action as Pepper, at the delegated person's current Projects permission and record scope. Each write needs an idempotency key and appears in the record's activity as done by an AI connection for that person.

MCP tool	HTTP after `/api/v1/`	Scope	What it does
`work_mine`	`GET work/mine`	`engagements:read`	Read My work as the person sees it: today's tasks, this week's and undated tasks, follow-ups, cards and running time. Only the person's own work.
`work_settings`	`GET work/settings`	`engagements:read`	Read the work settings: week start, working days and hours, time rounding and the default billing for new projects.
`time_defaults`	`GET time/defaults`	`engagements:read`	Read the defaults the time form fills in for a task, project, person and date: billable, rate and project.
`time_timesheet`	`GET time/week`	`engagements:read`	Read a weekly timesheet as the Timesheet screen shows it: rows per project and task, minutes per day and totals.
`time_timer`	`GET time/timer`	`engagements:read`	Read the person's timer: `state` is `running`, `paused` or `none`, with its entry or null.
`tasks_statuses`	`GET tasks/statuses`	`engagements:read`	Read the task statuses in order with the done status, and the revision tasks_statuses_save needs.
`tasks_statuses_save`	`POST tasks/statuses`	`engagements:prepare`	Replace a project's task statuses (or the defaults) in order, with exactly one done status. A status in use moves its tasks to the first status. A stale revision is refused.
`tasks_move`	`POST tasks/{id}/status`	`engagements:prepare`	Move a task to another status of its project at its current version.
`tasks_reopen`	`POST tasks/{id}/reopen`	`engagements:prepare`	Reopen a completed task.
`tasks_assign`	`POST tasks/{id}/assignee`	`engagements:prepare`	Give a task to a person or team, or clear the assignee.
`tasks_reschedule`	`POST tasks/{id}/dates`	`engagements:prepare`	Change a task's start and due date.
`tasks_watch`	`POST tasks/{id}/watch`	`engagements:prepare`	Watch a task, or stop watching it, to get its updates in the person's inbox.
`tasks_link`	`POST tasks/{id}/links`	`engagements:prepare`	Set the tasks that block this task. An empty list clears them.
`tasks_archive`	`POST tasks/{id}/archive`	`engagements:prepare`	Archive a task, or restore it.
`tasks_tag`	`POST tasks/{id}/tags`	`engagements:prepare`	Add a tag to a task.
`tasks_attach_project`	`POST tasks/{id}/project`	`engagements:prepare`	Move a task without a project into a project the person may use.
`tasks_from_card`	`POST cards/{id}/task`	`engagements:prepare`	Turn a board card into a task, optionally in a project, linked back to the card. The card stays on its board.
`time_update`	`PUT time/{id}`	`engagements:prepare`	Correct a time entry the person may edit at its current version. Invoiced time is refused.
`time_delete`	`POST time/{id}/delete`	`engagements:prepare`	Delete a time entry the person may edit. A running or invoiced entry is refused.
`time_cell`	`POST time/cell`	`engagements:prepare`	Set the minutes of one timesheet cell (person, project or task, date) as the Timesheet does: it changes or adds one entry, or removes them at 0.
`engagements_scope`	`POST engagements/{id}/scope`	`engagements:prepare`	Record a new agreed scope for a fixed-price project at its current version. Earlier scopes stay in the history.
`engagements_milestone_state`	`POST engagements/{id}/milestones/state`	`engagements:prepare`	Move a milestone to planned, completed, approved (ready to bill, confirmed) or withdrawn (confirmed). An invoiced milestone does not change.
`engagements_settings`	`POST engagements/{id}/settings`	`engagements:prepare`	Change an open project's billing, rounding, grouping, task prefix, rate and budget at its current version. Money is an exact minor-unit string.
`engagements_import_quote_lines`	`POST engagements/{id}/quote-lines`	`engagements:prepare`	Copy the lines of the project's accepted quote into milestones or tasks, once.
`views_engagement`	`GET views/engagement`	`engagements:read`	Read a view of the engagement records the delegated user may see, like the app's list, table, board, calendar, timeline and gallery: search, filters, sort, group and columns. Counts and per-currency totals cover the whole filtered set inside the user's scope; amounts are exact minor-unit strings with the currency scale. Filters: title (text: contains, is); customer (relation: is); state (enum: is, in; values open, closed); currency (text: contains, is); created (date: on, before, after, between); closed (date: on, before, after, between); updated (date: on, before, after, between). Invalid criteria are refused, never ignored. A table or list pages with limit and next_cursor; keep the other arguments the same.
`views_time_entry`	`GET views/time_entry`	`engagements:read`	Read a view of the time_entry records the delegated user may see, like the app's list, table, board, calendar, timeline and gallery: search, filters, sort, group and columns. Counts and per-currency totals cover the whole filtered set inside the user's scope; amounts are exact minor-unit strings with the currency scale. Filters: entry_date (date: on, before, after, between); person (relation: is); project (relation: is); task (relation: is); minutes (number: eq, gt, lt, between); billable (boolean: is); rate_source (enum: is, in; values entry, task, project, person, none); note (text: contains, is); state (enum: is, in; values open, allocated, invoiced); created (date: on, before, after, between). Invalid criteria are refused, never ignored. A table or list pages with limit and next_cursor; keep the other arguments the same.
`views_task_bulk`	`POST views/task/bulk`	`engagements:prepare`	Run one bulk action of the task view on up to 100 records, as the view's selection bar does: assign (payload: assignee); status (payload: status); due (payload: date); tag (payload: tag); archive (confirmed: true). Each record runs the ordinary action on its own; refusals are listed and do not undo the others.
`views_task_move`	`POST views/task/move/{id}`	`engagements:prepare`	Move one task to another lane of a board layout, as dragging a card does. The owning action runs and checks the move.
`decisions_options`	`GET decisions/options`	`engagements:read`	Find the customers, contacts, projects, deals, quotes or files a proof or job page can link, as the widget editor's picker does: up to 8 matches for q, or the given ids.

A change to a task, entry, project or milestone needs its current version where the tool asks for one; a stale version returns 409 with the current record. tasks_statuses_save replaces the project's status list at the revision that tasks_statuses returned, so read the list first. Time corrections follow the person's edit rights: an employee corrects and deletes their own entries, a manager also other people's entries. Billed time cannot change. time_timesheet returns the same week as the timesheet screen.

Prepare an invoice from tracked time

Project creation through engagements_create accepts billing_mode: fixed, hourly or mixed. It defaults to fixed. Project rate, budget, increment and status configuration stay on the project screen.

Read engagements_get for the project and projects_unbilled for its unbilled work.
Call engagements_preview_invoice with the project id, issue_date, due_date and a time object containing from and to.
Optional: put person_id, tax_rate_id and grouping (task, person, day, single) in time. Omitting tax_rate_id uses the active default; sending null applies no tax to the time lines. For mixed billing, include milestones as a map of milestone IDs to their current versions.
Review the returned lines and totals. Copy selection to time.entries and projectVersion to project_version without changing their values.
Call engagements_prepare_invoice with that input and a stable idempotency key.
Open the returned draft. For issue, follow the separate approval flow.

The preview reserves nothing. Preparation reserves each source once and locks it. If a source or the project changes, refresh the preview. Deleting an unissued draft releases its entries; credits and cancellation after issue do not. See Bill tracked time for rounding and correction examples.

Jobs

Settings > Agent connections > Jobs describes the available sequences.

Job	Example	Sequence and result
Log time	"Log two hours on WEB-130 for today."	Find the task, then `time_log` with 120 minutes. The stable key prevents a duplicate entry
Project status	"Show the progress, unbilled work, budget and margin for Acme."	`engagements_get`, `projects_unbilled` and `projects_margin`; current scope and financial permissions apply
Invoice unbilled time	"Invoice the unbilled time for Acme this month."	Read the project, preview the selection, prepare its draft, then request human confirmation for issue

Invoice issue, sending and payment recording are separate steps. Each needs your decision or a matching rule with limits; see Approve sensitive steps. Task descriptions, comments and agreement references are record data, never instructions to bypass that approval.