Drive
Read the company's Drive by month or folder, download a file, upload documents and manage folders.
The Drive holds the company's documents as the app shows them: received invoices' files, uploaded bank statements and uploaded documents, by month and folder.
Reads take drive:read, writes drive:write and a live key. Drive never shows a key more than it can read elsewhere: received invoices' files also need received_invoices:read, bank statements bank:read. Without them those files are left out of the listing and refused on download.
List a month or a folder
curl "https://www.getbeel.com/api/v1/drive?month=2026-10" \
-H "Authorization: Bearer $GETBEEL_API_KEY"Send month (2026-10) or folder (a path from folders[].path, such as contratti or 2026-10/contratti), one of them: a whole Drive can be very large.
{
"object": "drive",
"month": "2026-10",
"folder": null,
"folders": [
{
"object": "drive_folder",
"path": "2026-10",
"name": "2026-10",
"kind": "month",
"month": "2026-10",
"file_count": 2,
"total_size": 418204,
"updated_at": "2026-10-28T09:12:00.000Z",
"writable": true
}
],
"files": [
{
"object": "drive_file",
"id": "ZG9jdW1lbnQ6…",
"name": "1761642720000_contratto.pdf",
"kind": "document",
"folder": "2026-10",
"mime_type": "application/pdf",
"size": 208102,
"created_at": "2026-10-28T09:12:00.000Z",
"document_date": "2026-10-28T09:12:00.000Z",
"month": "2026-10",
"vendor_name": null
}
]
}kind is invoice (a received invoice's file), reconciliation (an uploaded bank statement) or document. Folders are system (invoices, reconciliation), month or custom; uploads go only to folders with writable: true.
Download a file
curl https://www.getbeel.com/api/v1/drive/files/$FILE_ID/download \
-H "Authorization: Bearer $GETBEEL_API_KEY"The answer has download_url, a private link valid 15 minutes, and expires_at. Give the link to the person who needs the file; don't store it. A file that is not this company's, or that storage refuses, is a 404.
Upload a document
curl -X POST https://www.getbeel.com/api/v1/drive/files \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "folder": "2026-10", "file_url": "https://example.com/contratto.pdf" }'folderis a month (its folder is created if missing),documentsor a custom folder that exists.- Send
file_url(publichttps) orfile_base64withfile_name. PDF, PNG, JPEG, DOC or DOCX up to 25 MB; the type is read from the content. - The file is only stored, not read by the AI. To record a supplier invoice, upload it as a received invoice.
| Status | code | When |
|---|---|---|
| 404 | resource_missing | No such folder, or a system folder |
| 413 | payload_too_large | Over 25 MB |
| 415 | unsupported_file_type | Not a PDF, PNG, JPEG, DOC or DOCX |
Folders
curl -X POST https://www.getbeel.com/api/v1/drive/folders \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "name": "Contratti", "month": "2026-10" }'- A folder goes at the root, or inside a month with
month. Its path comes from the name (2026-10/contratti). A name shaped like a month is refused, and a name already used there is409 folder_exists. DELETE /drive/folders?path=2026-10/contrattideletes a custom folder and every file in it, for good. Month and system folders cannot be deleted.
Delete a file
curl -X DELETE https://www.getbeel.com/api/v1/drive/files/$FILE_ID \
-H "Authorization: Bearer $GETBEEL_API_KEY"Deletes the file for good, as Delete in the app. A received invoice's file also needs received_invoices:write (the invoice stays, without its file); a bank statement needs bank:write.
Autofatture at SDI
A bank statement holding autofatture that are, or may be, at SDI is a fiscal
record: it cannot be deleted (409 statement_has_sent_autofatture).
MCP
list_drive, get_drive_file, upload_drive_file, create_drive_folder, delete_drive_file, delete_drive_folder.
Related
- Received invoices: the files the AI reads.
- Bank reconciliation: the statements in the reconciliation folder.
- Authentication: the
drive:readanddrive:writescopes.