Uploads
BlueSuite MCP tools for uploads
See connection and authentication and workflow rules before calling these tools.
Related REST API and behavior.
Attach a file (receipt, photo, PDF, document, video, audio) to a parent entity (contact, request, quote, job, invoice, event, or timesheet). Also used to upload line item images: pass module_type="workspace", module_id = workspace ID (call get_workspace first if needed), category="line_item", is_public=true, then use the returned path and id as image_path/image_id in a quote/invoice/job line item. Provide the file via file (a user-attached file from the chat, preferred when available), source_url (a URL to fetch), or base64_data (raw bytes). Max file size is 100 MB. Allowed MIME types: image/jpeg, image/png, image/webp, image/gif, image/avif, application/pdf, Word/Excel/PowerPoint docs, CSV, plain text, video (mp4/avi/mov), audio (aac/mp3/wav).
| Field | Type / accepted values | Required | Details |
|---|
module_type | "contact", "request", "quote", "job", "invoice", "event", "timesheet", "workspace" | Yes | Parent entity type. Use "workspace" only when paired with category="line_item" for line item images. |
module_id | integer | Yes | ID of the parent entity in the current workspace. For module_type="workspace", pass the workspace ID itself. |
file | object | No | A file attached by the user in the chat. Preferred over source_url/base64_data when the host populates it. Extra fields injected by the host are ignored. |
file.download_url | string | When parent supplied | HTTPS URL the server can fetch the file bytes from. Format: uri. |
file.file_id | string | When parent supplied | Opaque file identifier from the host. |
file.file_name | string | No | Original filename, if the host provides it. |
file.mime_type | string | No | MIME type hint from the host. Validated against the server allowlist after fetch. |
source_url | string | No | HTTPS URL to fetch the file from. Use when you have a public URL but no chat-attached file. Format: uri. |
base64_data | string | No | Base64-encoded file bytes. Use only when neither file nor source_url is available. When using this, mime_type and file_name are required. |
mime_type | "image/jpeg", "image/jpg", "image/png", "image/webp", "image/gif", "image/avif", "image/heic", "image/heif", "application/pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "text/csv", "text/plain", "application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-powerpoint", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "video/mp4", "video/x-msvideo", "video/avi", "video/quicktime", "audio/aac", "audio/mpeg", "audio/wav" | No | MIME type of the file. Required with base64_data; with file/source_url, falls back to the response Content-Type. Must be one of the accepted upload types. |
file_name | string | No | Original filename. Required with base64_data; with file/source_url, derived from the URL path. |
category | "attachment", "internal", "public", "expense", "line_item" | No | How the file should be tagged. Defaults to "attachment". Use "expense" for receipts on jobs. Use "line_item" (only with module_type="workspace") for line item images. |
name | string | No | Display name for the link. Defaults to the file name. |
description | string | No | Optional description shown alongside the file. |
is_public | boolean | No | When true, the file is stored in the public bucket and gets a permanent unauthenticated URL. Default: false (private bucket, signed URLs that expire). |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
List files attached to a parent entity (contact, request, quote, job, invoice, event, or timesheet). Returns paginated upload links with fresh signed URLs.
| Field | Type / accepted values | Required | Details |
|---|
module_type | "contact", "request", "quote", "job", "invoice", "event", "timesheet", "workspace" | Yes | Parent entity type. |
module_id | integer | Yes | Parent entity ID. |
category | "attachment", "internal", "public", "expense", "line_item" | No | Filter by category (e.g. only "expense" receipts). |
page | JSON value | No | Page number (default: 1). |
per_page | integer | No | Results per page (default: 25, max 100). minimum: 1. maximum: 100. |
| 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. |
Get a single upload link with a fresh signed URL. The link_id is the ID returned by upload_file or list_files.
| Field | Type / accepted values | Required | Details |
|---|
link_id | integer | Yes | Upload link 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 the name, description, or category of an existing upload link. The underlying file bytes cannot be replaced, delete the link and re-upload to change the file itself.
| Field | Type / accepted values | Required | Details |
|---|
link_id | integer | Yes | Upload link ID. |
name | string | No | New display name. |
description | string or null | No | New description (or null to clear). |
category | "attachment", "internal", "public", "expense", "line_item" | No | New category. |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Remove a file attachment from its parent entity. If the underlying file is not linked to any other entity, the file is also permanently deleted from storage.
| Field | Type / accepted values | Required | Details |
|---|
link_id | integer | Yes | Upload link 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.