Find tools and read records

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

AI is optional. You confirm invoice issuance in Pepper.

Endpoints

GET /api/v1/tools lists granted tools from the installed module registry. Each entry gives its HTTP method, path, scope and input schema.

Calls also need the delegated user's current permissions. A listed grant does not establish that every record or action is available.

Existing connections with individual pilot capabilities keep those capabilities. New connections use the scope groups shown in Permitted access.

Customer and document lists accept search, limit and after. For example, use /api/v1/customers?search=Acme&limit=25.

The view tools take the same view as the app: layout, search, filters (a list of field, op and value), sort, dir, group, columns, date, end, month, page and per_page (25, 50 or 100). Amounts in a filter are exact decimal text, such as "100.50". The answer has the rows, the total count, the group counts and the totals for each currency, all inside the delegated person's access. A criterion that the tool cannot apply exactly is refused with 422. The tools read only; they do not move or change records. See Views of your records.

Customer search returns active permitted IDs and names. Document lists return summaries; an individual read adds public notes, reference and line fields.

Summaries include type, status, number, draft code, customer ID, dates, currency, lock_version, monetary strings, connection ID and href.

A new draft has no document number. Internal notes, customer addresses, bank details, credentials and signed download links stay outside document responses.

People lists accept search, limit, after and optional team_id. Team lists accept search, limit and after.

People reads cover active staff, excluding guests. Responses include name, work email, job title, skills, teams, manager and time zone.

Individual people reads also include weekly working hours. They exclude private contact details, rates, time-off records and sign-in settings.

Team reads include live teams, descriptions, lead IDs and active staff member IDs.

Comment reads need record_type (customer, document, engagement or purchase) and record_id. They return the comments and replies of a record the delegated person may open, with author, time and text. A record outside that scope returns 404 with no comment. A mention of someone outside the person's directory reads as @someone.

Notification reads accept kind (mention, assignment, comment or update), unread, limit and after. They return the delegated person's visible inbox rows, newest first, with a short excerpt and the record title. Reading does not mark anything read. Neither tool writes comments.

These tools do not send documents, record payments, export files or administer taxes and bank accounts. Item catalog tools are described in Business tools. There is no full-ledger endpoint.

For event history and the last integrity result, read Audit tools. These read tools cannot export evidence or erase personal fields.

Customer context

customers_context requires a customer id and customers.view. Its customer object uses the same identity and contacts as the customer page.

Optional sections selects documents, activity and files. Omitting it requests all three. An empty list returns customer identity only.

Each section also needs its grant, module and current permission. Unavailable sections are null; a permitted empty section has no rows. Documents need invoices:read, activity needs collaboration:read, and files need files:read.

Open documents include drafts, outstanding invoices and open quotes or proformas. Each document uses the same summary fields and exact balance as the customer page.

Documents and files return 25 rows per page. Use document_page or file_page; next_page is null at the end. Use the activity cursor as activity_before for older entries.

Files include ID, name, MIME type, byte size, current version ID and a Pepper link. A file linked to a private board still needs that board's current access. No download credential or signed link is returned.

Current overdue balances

invoices_receivables needs invoices:finance-summary, financial_summary.view and document access. It does not require data-export permission.

The result contains as_of, currency-separated totals, and documents with 50 rows per page. Monetary values are exact minor-unit strings with their currency and scale. Never add different currencies together.

Optional inputs are customer_id, due_before (YYYY-MM-DD) and page. due_before narrows current overdue invoices to those due on or before that date. It does not reconstruct a historical balance.

Totals cover all matching permitted invoices, even when only one page is returned. Use next_page to read the remaining record links. Each row uses the same balance and summary fields as the customer page.

A changed permission, owner, active-user state or private-file membership takes effect on the next call. Neither job tool sends a reminder, records a payment or changes a document.