conecto. Get started
Files

Find files

files_list · Reads only · Markdown

The business's files, newest first, filtered by name, words inside, tags, type, correspondent, document date or fields.

Free*

*Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads.

An example

Find all invoices from Cascade Bike Supply this year.

Your agent callsfiles_listFree*

The example business is Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. The reply is the one the tool really gives.

With these arguments
{
  "correspondent": "Cascade Bike Supply",
  "document_type": "Invoice",
  "date_from": "2026-01-01"
}
What comes back
{
  "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
  }
}

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.

What it does

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).

What comes back

files: each with its file_id, name, title, tags, type, correspondent, document date, fields, text status and a fresh download link; and the total. Every reply also carries cost_usd and balance_usd.

Inputs

NameTypeWhat it is
name_containsstringUp to 100 characters.
wordsstringWords in the file's text. Up to 200 characters.
tagsarray of stringsUp to 20 items.
tags_matchstringOne of: all,any. Default: all.
untaggedbooleanDefault: false.
document_typestringUp to 60 characters.
correspondentstringUp to 200 characters.
date_fromstringDocument date on or after, YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
date_tostringDocument date on or before, YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
fieldsarray of objectsUp to 10 items.
fields[].fieldRequiredstring1 to 60 characters.
fields[].valuestring or number or booleanUp to 2,000 characters.
fields[].minstring or number or booleanUp to 2,000 characters.
fields[].maxstring or number or booleanUp to 2,000 characters.
fields[].currencystringMatches ^[A-Za-z]{3}$.
fields[].emptybooleantrue: files without a value; false: with one.
has_textboolean
sourcestringOne of: upload,url,link,tool,email,phone,export.
sortstringOne of: added,document_date,title. Default: added.
orderstringOne of: asc,desc.
limitinteger1 to 100. Default: 20.
offsetintegerAt least 0. Default: 0.
link_hoursintegerHow long the download link works, in hours (up to 168, one week). 1 to 168. Default: 24.

The call

Over MCP, call files_list on https://api.conecto.chat/mcp/files. Over REST:

Terminal
curl -X POST 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"}'

When it refuses

A refused call costs nothing and says what to do next.

CodeWhenWhat to do
not_found404A tag, document type, field or correspondent named is not defined yet.Define it with files_define first; files_definitions lists what exists.
invalid_input400A date or a field filter is not valid.Send dates like 2026-01-01.

More Files tools

All 13 tools

Give this to your agent.

Set up Conecto from https://conecto.chat/SKILL.md