# Drive (https://docs.getbeel.com/en/api/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 [#list-a-month-or-a-folder]

```bash
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.

```json title="Response"
{
  "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 [#download-a-file]

```bash
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 [#upload-a-document]

```bash
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" }'
```

- `folder` is a month (its folder is created if missing), `documents` or a custom folder that exists.
- Send `file_url` (public `https`) or `file_base64` with `file_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](/en/api/received-invoices#upload-an-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 [#folders]

```bash
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 is `409 folder_exists`.
- `DELETE /drive/folders?path=2026-10/contratti` deletes a custom folder and every file in it, for good. Month and system folders cannot be deleted.

## Delete a file [#delete-a-file]

```bash
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`.

<Callout type="warn" title="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`).
</Callout>

## MCP [#mcp]

`list_drive`, `get_drive_file`, `upload_drive_file`, `create_drive_folder`, `delete_drive_file`, `delete_drive_folder`.

## Related [#related]

- [Received invoices](/en/api/received-invoices): the files the AI reads.
- [Bank reconciliation](/en/api/bank-reconciliation): the statements in the reconciliation folder.
- [Authentication](/en/api/authentication): the `drive:read` and `drive:write` scopes.
