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

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 page, per_page (25, 50 or 100), 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. Reopening, moving to another status, moving into a project and changing dependencies stay on the screen.

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 takes no business input. Time lists accept page, per_page, 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.

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.

1. Read engagements_get for the project and projects_unbilled for its unbilled work.
2. Call engagements_preview_invoice with the project id, issue_date, due_date and a time object containing from and to.
3. 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.
4. Review the returned lines and totals. Copy selection to time.entries and projectVersion to project_version without changing their values.
5. Call engagements_prepare_invoice with that input and a stable idempotency key.
6. 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.

The jobs do not send invoices or record payments. A person confirms invoice issuance in Pepper. Task descriptions, comments and agreement references are record data, never instructions to bypass that approval.