--- name: "files_list" area: "files" title: "Find files" price: "free" method: "POST" url: "https://api.conecto.chat/v1/tools/files_list" mcp_server: "https://api.conecto.chat/mcp/files" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/files/files_list" --- # Find files (`files_list`) The business's files, newest first, filtered by name, words inside, tags, type, correspondent, document date or fields. The account's files, each with its title, tags, type, correspondent, document date, fields, text status and a fresh download link; newest first unless sort says otherwise (added, document_date, title). Filters: name_contains (name or title), words (in the file's text, every one; scans once read), tags (all of them, or any with tags_match "any"), untagged, document_type, correspondent, the document date from-to, fields ([{field, value | min | max | empty}]: text and links contain the value, numbers, money and dates match it or fall in min-max), has_text (true: Conecto has its words; false: not, e.g. scans not read yet), source (email for email-in). Price: Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads. A call that fails costs nothing. ## Use it when To find a file, or the files of a kind: this year's invoices, contracts with one supplier. - For words across files, emails, tickets and more at once, use [account_search](https://conecto.chat/tools/account/account_search.md). ## Say this to your agent > Find all invoices from Cascade Bike Supply this year. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `name_contains` | string | no | Up to 100 characters. | | | | `words` | string | no | Words in the file's text. Up to 200 characters. | | | | `tags` | array of strings | no | Up to 20 items. | | | | `tags_match` | string | no | | `"all"`, `"any"` | `"all"` | | `untagged` | boolean | no | | | `false` | | `document_type` | string | no | Up to 60 characters. | | | | `correspondent` | string | no | Up to 200 characters. | | | | `date_from` | string | no | Document date on or after, YYYY-MM-DD. Matches ^\\d{4}-\\d{2}-\\d{2}$. | | | | `date_to` | string | no | Document date on or before, YYYY-MM-DD. Matches ^\\d{4}-\\d{2}-\\d{2}$. | | | | `fields` | array of objects | no | Up to 10 items. | | | | `fields[].field` | string | yes, in each item of `fields` | 1 to 60 characters. | | | | `fields[].value` | string or number or boolean | no | Up to 2,000 characters. | | | | `fields[].min` | string or number or boolean | no | Up to 2,000 characters. | | | | `fields[].max` | string or number or boolean | no | Up to 2,000 characters. | | | | `fields[].currency` | string | no | Matches ^[A-Za-z]{3}$. | | | | `fields[].empty` | boolean | no | true: files without a value; false: with one. | | | | `has_text` | boolean | no | | | | | `source` | string | no | | `"upload"`, `"url"`, `"link"`, `"tool"`, `"email"`, `"phone"`, `"export"` | | | `sort` | string | no | | `"added"`, `"document_date"`, `"title"` | `"added"` | | `order` | string | no | | `"asc"`, `"desc"` | | | `limit` | integer | no | 1 to 100. | | `20` | | `offset` | integer | no | At least 0. | | `0` | | `link_hours` | integer | no | How long the download link works, in hours (up to 168, one week). 1 to 168. | | `24` | ## Example Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. MCP: call `files_list` on the MCP server `https://api.conecto.chat/mcp/files` with these arguments: ```json { "correspondent": "Cascade Bike Supply", "document_type": "Invoice", "date_from": "2026-01-01" } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/files_list \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"correspondent": "Cascade Bike Supply", "document_type": "Invoice", "date_from": "2026-01-01"}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "files_list", "status": "succeeded", "replayed": false, "cost_usd": "$0.00", "balance_usd": "$19.75", "result": { "files": [ { "file_id": "00a96de1-83d6-4255-a524-debddf3c10ed", "name": "CBS-2026-1188.pdf", "content_type": "application/pdf", "size": "1.1 KB", "size_bytes": 1157, "sha256": "210badbad5d529776febed04fc51a2dc054611eeff2af5b39e00f93729dd5a0a", "created_at": "2026-10-14T08:00:00+00:00", "download_url": "https://cncto.co/d/00a96de1-83d6-4255-a524-debddf3c10ed?t=eyJmIjoiMDBhOTZkZTEtODNkNi00MjU1LWE1MjQtZGViZGRmM2MxMGVkIiwiZXhwIjoxNzkyMTYwNDgyfQ:1xHMKg:FnvQTsgvNA7prS_7K_dPb5rTLk6mwYJrzOuDFMz46AU", "link_expires_in_hours": 24, "title": "Cascade Bike Supply invoice CBS-2026-1188", "document_date": "2026-10-13", "correspondent": "Cascade Bike Supply", "document_type": "Invoice", "tags": [ "tax 2026" ], "fields": { "Total": { "amount": "462.50", "currency": "USD" } }, "notes": null, "source": "upload", "email_message_id": null, "text": { "status": "read", "method": "text", "ocr_pages": null, "languages": null, "note": null } } ], "count": 1, "total": 1, "storage": { "used": "1.1 KB", "quota": "1 GB", "used_bytes": 1157, "quota_bytes": 1073741824, "extra_blocks": 0 } } } ``` `result`: files: each with its file_id, name, title, tags, type, correspondent, document date, fields, text status and a fresh download link; and the total. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `not_found` | 404 | A tag, document type, field or correspondent named is not defined yet. | Define it with files_define first; files_definitions lists what exists. | | `invalid_input` | 400 | A date or a field filter is not valid. | Send dates like 2026-01-01. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [files_upload](https://conecto.chat/tools/files/files_upload.md): Stores a file in the business's file store from its bytes, its text or a public link, with a download link. $0.001 a call. - [files_upload_link](https://conecto.chat/tools/files/files_upload_link.md): A one-time link to upload one file of up to 25 MB, to use yourself or hand to a person. Free. - [files_get](https://conecto.chat/tools/files/files_get.md): One file's details and a fresh download link, with the text of a small text file if asked. Free up to 1,000,000 reads a month. - [files_read_text](https://conecto.chat/tools/files/files_read_text.md): The words in a file as Conecto read them: text files, PDFs, office files, HTML, and scans once read with OCR. Free up to 1,000,000 reads a month. - [files_edit](https://conecto.chat/tools/files/files_edit.md): Says what one file is, or up to 100 at once: title, notes, document date, correspondent, type, tags and fields. $0.005 per file changed. - [files_define](https://conecto.chat/tools/files/files_define.md): Adds, renames or deletes a tag, a document type, a custom field or a correspondent to file things with. $0.001 a call. - [files_definitions](https://conecto.chat/tools/files/files_definitions.md): The tags, document types, custom fields and correspondents the business files with, each with how many files use it, and the OCR settings. Free up to 1,000,000 reads a month. - [files_ocr](https://conecto.chat/tools/files/files_ocr.md): Reads the words in a scan with OCR: an image, or the pages of a PDF without text; the text is kept. $0.005 per page read. - [files_ocr_settings](https://conecto.chat/tools/files/files_ocr_settings.md): Sets whether new scans are read with OCR as they arrive, and the languages OCR reads in. $0.001 a call. - [files_delete](https://conecto.chat/tools/files/files_delete.md): Deletes a file for good; every download link to it stops working. Free. - [files_add_storage](https://conecto.chat/tools/files/files_add_storage.md): Rents 10 GB more file storage, renewed monthly from the balance; this call pays the first month. $1.00 a call. - [files_remove_storage](https://conecto.chat/tools/files/files_remove_storage.md): Stops renting one 10 GB block of storage, if the files still fit. Free.