> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Search connected files and read bounded file content

Read OneDrive and SharePoint, or Google Drive through a [connection](https://docs.oneshotagent.com/api-reference/connections/overview.md). Choose `connection_id` from `GET /v1/connections` by `system` and `account_label`. The signed-in user's permissions apply, including shared drives.

## Search files

`POST /v1/tools/files/search` (`files_search`) requires `connection_id` and a non-empty `query`. Optional `folder_id` restricts search to that folder: recursively for Microsoft 365, or direct children for Google Drive. `limit` defaults to 25, maximum 50. Pass `next_cursor` as `cursor` with unchanged filters. Microsoft search indexing can lag file changes.

```json theme={null}
{
  "connection_id": "00000000-0000-4000-8000-000000000001",
  "query": "bank statement",
  "limit": 25
}
```

The response contains `data.records`, `data.receipt_id`, and `data.next_cursor` when another page exists. Each record has `id`, `name`, `path`, `content_type`, `size`, `modified_at` and `source` (`system`, `id`). Unavailable descriptive fields are null. Folders are omitted; continue while a cursor is present.

Pass opaque IDs unchanged. Microsoft folder IDs can be raw item IDs or drive/item references.

## Read a file

`POST /v1/tools/files/read` (`files_read`) takes `connection_id` and `file_id` from the search results. It returns `name`, `content_type`, `size` and `base64` inside `data`, alongside `receipt_id`.

Google Drive currently supports Google Sheets as CSV (`text/csv`). Optional `sheet` selects a tab by its exact name; omitting it selects the first tab. CSV uses displayed values, escaping delimiters and newlines and preserving interior empty cells. Empty tabs return empty CSV. The cap applies to UTF-8 bytes including escaping. Missing tabs refund payment. Other providers refuse `sheet`.

Ordinary Drive bytes and Google Docs/Slides plain-text exports are not supported yet: reads refuse before payment; metadata remains searchable.

Content is limited to 10 MB (10,485,760 bytes). Missing or invalid required metadata and known oversized content refuse before payment. Sheets have no exported size in metadata, so their CSV size is checked during the read. Downloads are bounded while streaming and only use Microsoft 365 tenant download endpoints, without following redirects. A file that changes size or fails to download after payment is refused and refunded as account credit.

These tools never modify files or save fetched data in logs, receipts, jobs or goal history. Later steps must read again.

Invalid inputs return `400 invalid_request`, unsupported sizes return `400 not_supported`, another agent's connection returns `404 connection_not_found`, and revoked or expired connections return 409. Unavailable file data returns 503. Payment uses x402 or account credit; amounts are on [Pricing](https://docs.oneshotagent.com/pricing.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.