---
name: "files_upload"
area: "files"
title: "Upload a file"
price: "$0.001"
method: "POST"
url: "https://api.conecto.chat/v1/tools/files_upload"
mcp_server: "https://api.conecto.chat/mcp/files"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/files/files_upload"
---

# Upload a file (`files_upload`)

Stores a file in the business's file store from its bytes, its text or a public link, with a download link.

Store a file in the account's private file store and get a download link for it. Give exactly one of: content_base64 (the bytes, or a data: URL), text (for text files: Markdown, CSV, JSON...), or url (a public https link we fetch). Inline content is limited to 1.5 MB; for bigger files (up to 25 MB) use files_upload_link. 1 GB of storage is free. duplicate_of names a stored file with the same bytes; the upload is kept anyway.

Price: $0.001 a call. A call that fails costs nothing.

## Use it when

A file should be kept or passed to another tool: a logo, a PDF, a spreadsheet.

- For a file a person sends, or one over 1.5 MB, use [files_upload_link](https://conecto.chat/tools/files/files_upload_link.md).

## Say this to your agent

> Keep this photo of the new walnut sample in our files.

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `name` | string | yes | File name, e.g. "quote.pdf". 1 to 200 characters. |  |  |
| `content_base64` | string | no | Up to 2,100,000 characters. |  |  |
| `text` | string | no | Up to 1,500,000 characters. |  |  |
| `url` | string | no | A public https:// link to the file. Up to 2,000 characters. |  |  |
| `content_type` | string | no | e.g. "application/pdf". Guessed from the name when left out. Up to 120 characters. |  |  |
| `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_upload` on the MCP server `https://api.conecto.chat/mcp/files` with these arguments:

```json
{
  "name": "walnut-sample.png",
  "content_base64": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAAFUlEQVR42mPUVlFgwAaYGHCAwSkBAFztAH+qHNFaAAAAAElFTkSuQmCC"
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/files_upload \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "walnut-sample.png", "content_base64": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAAFUlEQVR42mPUVlFgwAaYGHCAwSkBAFztAH+qHNFaAAAAAElFTkSuQmCC"}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "files_upload",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.001",
  "balance_usd": "$19.75",
  "result": {
    "file": {
      "file_id": "cc4a3738-fd9c-4418-a1a0-c5dd1876db58",
      "name": "walnut-sample.png",
      "content_type": "image/png",
      "size": "78 bytes",
      "size_bytes": 78,
      "sha256": "e5d9e4983b30319a1323ead2071cabd97613fc2dd87f411cb27461d9973d986f",
      "created_at": "2026-10-14T08:00:00+00:00",
      "download_url": "https://cncto.co/d/cc4a3738-fd9c-4418-a1a0-c5dd1876db58?t=eyJmIjoiY2M0YTM3MzgtZmQ5Yy00NDE4LWExYTAtYzVkZDE4NzZkYjU4IiwiZXhwIjoxNzkyMTYwNDgxfQ:1xHMKf:81nXm3ya6X9Yk1yswZRO1y5bt5bIGy95AkUcV938JVI",
      "link_expires_in_hours": 24
    },
    "storage": {
      "used": "78 bytes",
      "quota": "1 GB",
      "used_bytes": 78,
      "quota_bytes": 1073741824,
      "extra_blocks": 0
    },
    "duplicate_of": null
  }
}
```

`result`: file: its file_id, name, type, size, checksum, when it was added, and a download link with its expiry; storage: how much is used and free; and duplicate_of when the same bytes are stored already.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `invalid_input` | 400 | Not exactly one of content_base64, text or url was given, the base64 is not valid, or the file is empty. | Send exactly one of them. |
| `too_large` | 413 | The file is over 1.5 MB inline, or over 25 MB at all. | Use files_upload_link for big files. |
| `invalid_url` | 400 | The url is not a public https:// link. | Send a public https:// link. |
| `fetch_failed` | 422 | The link could not be fetched, or did not answer with the file. | Check the link opens without signing in. |
| `storage_full` | 409 | The file store has no room for the file. | Delete files with files_delete, or add room with files_add_storage. |

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_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_list](https://conecto.chat/tools/files/files_list.md): The business's files, newest first, filtered by name, words inside, tags, type, correspondent, document date or fields. Free up to 1,000,000 reads a month.
- [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.