Expenses
BlueSuite MCP tools for expenses
See connection and authentication and workflow rules before calling these tools.
Related REST API and behavior.
List expenses for a job. Expenses track costs associated with jobs (materials, subcontractors, permits, etc.).
| Field | Type / accepted values | Required | Details |
|---|
job_id | integer | Yes | Job ID |
page | integer | No | Page number (default: 1) |
per_page | integer | No | Results per page (default: 25) minimum: 1. maximum: 100. |
search | string | No | Search by name or description |
sort_by | "id", "name", "total", "date", "created_at", "modified_at" | No | Field to sort by. Unknown values fall back to the default sort. |
sort_direction | "asc", "desc" | No | Sort direction |
| Field | Type / accepted values | Required | Details |
|---|
data | array of object | Yes | The matching records for this page. |
pagination | object | No | How many more pages of results exist. Absent when the API returned an unpaged result. |
pagination.page | integer | When parent supplied | Current page number, 1-based. |
pagination.per_page | integer | When parent supplied | Number of results per page. |
pagination.total_pages | integer | When parent supplied | Total number of pages available. |
Create a new expense for a job. Expenses track costs such as materials, subcontractor fees, permits, etc. Provide a receipt via receipt (a user-attached file from the chat) or attachment (a storage path from a prior upload_file call).
| Field | Type / accepted values | Required | Details |
|---|
job_id | integer | Yes | Job ID |
name | string | Yes | Expense name/title |
description | string | No | Expense description. Omit when not needed. |
date | string | No | Expense date (YYYY-MM-DD) |
total | number | Yes | Expense amount |
receipt | object | No | A receipt file attached by the user in the chat. Preferred over attachment when the host populates it. The file is uploaded automatically and linked to the expense. |
receipt.download_url | string | When parent supplied | HTTPS URL the server can fetch the file bytes from. Format: uri. |
receipt.file_id | string | When parent supplied | Opaque file identifier from the host. |
receipt.file_name | string | No | Original filename, if the host provides it. |
receipt.mime_type | string | No | MIME type hint from the host. Validated against the server allowlist after fetch. |
attachment | string | No | Storage path of an already-uploaded file (from a prior upload_file call). Use only when not providing receipt. |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Get a single expense by ID for a job
| Field | Type / accepted values | Required | Details |
|---|
job_id | integer | Yes | Job ID |
expense_id | JSON value | Yes | Expense ID |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Update an existing expense for a job. Provide a new receipt via receipt (a user-attached file from the chat) or attachment (a storage path from a prior upload_file call). Pass attachment: "" to clear the existing receipt.
| Field | Type / accepted values | Required | Details |
|---|
job_id | integer | Yes | Job ID |
expense_id | JSON value | Yes | Expense ID |
name | string | No | Expense name/title |
description | string | No | Expense description |
date | string | No | Expense date (YYYY-MM-DD) |
total | number | No | Expense amount |
receipt | object | No | A new receipt file attached by the user in the chat. Replaces any existing receipt. Preferred over attachment when the host populates it. |
receipt.download_url | string | When parent supplied | HTTPS URL the server can fetch the file bytes from. Format: uri. |
receipt.file_id | string | When parent supplied | Opaque file identifier from the host. |
receipt.file_name | string | No | Original filename, if the host provides it. |
receipt.mime_type | string | No | MIME type hint from the host. Validated against the server allowlist after fetch. |
attachment | string | No | Storage path of an already-uploaded file, or empty string to clear the existing receipt. Use only when not providing receipt. |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Delete an expense from a job
| Field | Type / accepted values | Required | Details |
|---|
job_id | integer | Yes | Job ID |
expense_id | JSON value | Yes | Expense ID |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
The downloadable tool schemas include the full input and output contracts. Tables describe schema-level required fields; cross-field rules still apply.