Files

Data model

Files live in one folder tree per environment. A path is unique within the environment. Each file carries system fields that start with an underscore and any custom metadata you set.

# Every file has system fields next to its custom metadata:
{
    "status":       "pending",                       # custom metadata
    "_path":        "invoices/2026/acme.pdf",
    "_folder":      "invoices/2026",
    "_name":        "acme.pdf",
    "_mime_type":   "application/pdf",
    "_size":        48213,
    "_source":      "browser",                       # agent, browser, dashboard or api
    "_agent":       "billing",
    "_run_id":      "8f0c2d6e-...",
    "_session_id":  "session-billing-customer-42",
    "_id":          "550e8400-e29b-41d4-a716-446655440000",
    "_created_at":  "2026-10-17T10:30:00Z",
    "_updated_at":  "2026-10-17T10:30:00Z",
}

Saving to a path that already exists stores the new file under a numbered name, such as acme (2).pdf, unless the write asks to overwrite. Files are encrypted at rest with a separate key per environment.

How agents use files

• File tools list, read, write, move, and delete files.
• Browser downloads go straight into files with save_to, and web_browser_upload sends a stored file into an upload field with path.
• Custom tools call the same functions from connic.tools.

Limits

• Up to 1 GiB per file through the dashboard and the REST API.
• Up to 100 MiB per file through the browser tools.
• Up to 16 MiB per file_write call or single-request write. Larger files go through an upload.
• Up to 20 MiB for files an agent reads into its context. Larger files still work with the browser and custom tools.

Upload with the REST API

Uploads go in parts, so large files survive slow connections and a failed part can be sent again. Requests need the files.manage permission; listing, metadata, and download links need files.view. See the REST API reference for every endpoint.

# 1. Start the upload
curl -X POST "https://api.connic.co/v1/projects/{project_id}/files/{environment_id}/uploads" \
  -H "Authorization: Bearer cnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"path": "contracts/acme.pdf", "size": 48213, "metadata": {"customer": "acme"}}'

# 201 Created
# {"upload_url": "https://...", "token": "...", "part_bytes": 16777216, "part_count": 1, ...}

# 2. Send each part. Every part except the last is exactly part_bytes long.
curl -X PUT "$UPLOAD_URL/parts/1?token=$TOKEN" --data-binary @acme.pdf

# 3. Finish the upload
curl -X POST "$UPLOAD_URL/complete?token=$TOKEN"

Dashboard

The Files page in the project dashboard supports:

• Browsing folders, or every file below a folder
• Uploading files by picking them or dropping them on the page
• Filtering by source, and opening the files of a run or session from its details
• Downloading, moving, renaming, and deleting files and folders
• Viewing and editing a file's metadata

Billing

Stored files and downloaded bytes are billed from Project credit. Files an agent reads through the file tools are not billed as downloads. See Pricing for rates.