Project, purchase, item and report tools

For: developers connecting an HTTP or MCP client. Start with Agent API and AI clients.

AI is optional. You confirm invoice issuance in Pepper.

Projects, purchases and items

These tools use the same records and permissions as the app. Preparation saves the stated reversible change; it does not issue or send anything.

MCP tool	HTTP path after `/api/v1/`	Scope	Result
`engagements_list`	`GET engagements`	`engagements:read`	Permitted projects and work counts; money summaries need their own permission
`engagements_get`	`GET engagements/{id}`	`engagements:read`	Project, scopes, milestones and permitted linked records
`engagements_create`	`POST engagements`	`engagements:prepare`	Saved project; no client agreement
`engagements_milestone`	`POST engagements/{id}/milestones`	`engagements:prepare`	Planned milestone against an existing agreement
`engagements_close`	`POST engagements/{id}/state`	`engagements:prepare`	Closed or reopened project; unfinished work prevents closure
`engagements_preview_invoice`	`POST engagements/{id}/invoice-preview`	`engagements:read`	Exact preview of approved milestones; saves nothing
`engagements_prepare_invoice`	`POST engagements/{id}/invoice-draft`	`engagements:prepare`	Saved invoice draft; reserves the selected approved milestones once
`purchases_list`	`GET purchases`	`purchases:read`	Permitted purchases; totals need financial-summary permission
`purchases_get`	`GET purchases/{id}`	`purchases:read`	Purchase and permitted files and project links
`purchases_create`	`POST purchases`	`purchases:prepare`	Saved unpaid purchase with PHP-calculated totals
`purchases_update`	`PUT purchases/{id}`	`purchases:prepare`	Saved purchase changes; keeps existing payment details
`items_list`	`GET items`	`items:read`	Catalog rows with exact prices
`items_get`	`GET items/{id}`	`items:read`	Editor fields and current version; requires item management
`items_create`	`POST items`	`items:prepare`	Saved catalog item
`items_update`	`PUT items/{id}`	`items:prepare`	Saved changes, including archive or restore

Lists accept page, per_page (25, 50 or 100; default 25) and search (100 characters maximum). Pagination returns page numbers and totals.

Use view to filter projects (open, closed), purchases (recorded, unpaid, nofile, voided) or items (all, active, inactive). Purchases also accept period.

Project reads need customers.view. Writes and invoice previews also need invoices.manage. Only a person can record agreement or approve a milestone.

Project creation needs title, customer_id and currency_code. A milestone needs the project id, current version, title, scope_id and unit_price.

Milestones can also include tax_rate_id and due_date. Closing or reopening needs the project id, current version and closed boolean.

Invoice preview and preparation need the project id, issue_date, due_date and milestones. Map each milestone ID to its current version.

Only approved, unreserved milestones qualify. Preparing an invoice does not approve the work. Issuing still needs your approval.

Purchase reads need purchases.view or purchases.view_own. Writes also need purchases.manage and access to that purchase.

Purchase creation needs supplier_id, purchase_date, currency_code and lines. Each line needs entry_mode (net or gross) and amount.

Optional line fields are description, tax, tax_rate_id and category_id. Optional purchase fields are reference, notes and engagement_id.

Purchase updates also need id and the current integer version. The saved currency stays fixed. The tools cannot record or clear payment details.

Item lists need items.view. Item detail and writes need items.manage, because the detail contains fields from the item editor.

Item creation needs name, unit_price, currency_code and unit_type. Unit types are hour, piece, day, kg and custom.

For custom, include custom_unit. Optional fields are sku, description, tax_rate_id, category_id and is_active.

Item updates need id, the current version from items_get, name, unit_price and unit_type. The saved currency stays fixed.

Set is_active to the string "0" to archive an item or "1" to restore it. Issued originals stay unchanged.

Send amounts as exact minor-unit strings: "12345" means EUR 123.45 or USD 123.45. "10001" means BHD 10.001.

Every write needs an idempotency key. An identical retry returns its original receipt after current permission and record checks.

Reports and safe settings

Report tools require reports:read, data.export and current document access. They return exact monetary strings, with integer record counts.

MCP tool	HTTP path after `/api/v1/`	Required inputs
`reports_aging`	`GET reports/aging`	`currency_code`
`reports_tax`	`GET reports/tax`	`currency_code`, `start_date`, `end_date`
`reports_customer_statement`	`GET reports/customer-statement`	`customer_id`, `currency_code`, `start_date`, `end_date`
`settings_read`	`GET settings/safe`	None; needs `settings:read` and `settings.manage`

Dates use YYYY-MM-DD. Aging and statements accept page and per_page (1–100; default 50). Tax results group the chosen period by rate.

Reports keep currencies separate. They do not convert currencies, file returns or export CSV files.

Settings reads return only these named fields:

company.name, company.country, company.currency, company.timezone.
localization.default_locale, localization.date_format, localization.time_format, localization.number_format, localization.week_start.
invoicing.default_payment_terms, invoicing.einvoice_readiness.

Credentials, keys, tokens, mail passwords and bank details never appear. Settings changes remain in the app.

Installation health

Optional AI access includes the installation.health read tool (installation_health in MCP), also available at GET /api/v1/installation/health. It requires settings:read and a current active owner or administrator.

The response contains checks, checkedAt and version. Each check contains its key, label, state, lastSuccess, message and a fix with label and href. States are working, warning, failing or never_seen. No credential, customer record or filesystem path is returned.

The tool reads the same results as Installation health. It changes no settings and runs no repair. You decide what to change.