Dateien

Datenmodell

Dateien liegen in einem Ordnerbaum pro Umgebung. Ein Pfad ist innerhalb der Umgebung eindeutig. Jede Datei hat Systemfelder mit Unterstrich am Anfang und beliebige eigene Metadaten.

# Jede Datei hat Systemfelder neben ihren eigenen Metadaten:
{
    "status":       "pending",                       # eigene Metadaten
    "_path":        "invoices/2026/acme.pdf",
    "_folder":      "invoices/2026",
    "_name":        "acme.pdf",
    "_mime_type":   "application/pdf",
    "_size":        48213,
    "_source":      "browser",                       # agent, browser, dashboard oder 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",
}

Wird an einen bereits belegten Pfad gespeichert, bekommt die neue Datei einen nummerierten Namen wie acme (2).pdf, außer der Schreibvorgang verlangt ausdrücklich das Überschreiben. Dateien werden im Ruhezustand mit einem eigenen Schlüssel pro Umgebung verschlüsselt.

So nutzen Agents Dateien

• File Tools listen, lesen, schreiben, verschieben und löschen Dateien.
• Browser-Downloads landen mit save_to direkt in den Dateien, und web_browser_upload lädt mit path eine gespeicherte Datei in ein Upload-Feld.
• Eigene Tools rufen dieselben Funktionen aus connic.tools auf.

Limits

• Bis zu 1 GiB pro Datei über das Dashboard und die REST API.
• Bis zu 100 MiB pro Datei über die Browser-Tools.
• Bis zu 16 MiB pro file_write-Aufruf oder Schreibvorgang in einer Anfrage. Größere Dateien gehen über einen Upload.
• Bis zu 20 MiB für Dateien, die ein Agent in seinen Kontext liest. Größere Dateien funktionieren weiterhin mit dem Browser und eigenen Tools.

Upload über die REST API

Uploads laufen in Teilen, damit große Dateien auch langsame Verbindungen überstehen und ein fehlgeschlagener Teil erneut gesendet werden kann. Anfragen brauchen die Berechtigung files.manage; Listen, Metadaten und Download-Links brauchen files.view. Alle Endpunkte stehen in der REST-API-Referenz.

# 1. Upload starten
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. Jeden Teil senden. Alle Teile außer dem letzten sind genau part_bytes lang.
curl -X PUT "$UPLOAD_URL/parts/1?token=$TOKEN" --data-binary @acme.pdf

# 3. Upload abschließen
curl -X POST "$UPLOAD_URL/complete?token=$TOKEN"

Dashboard

Die Seite Files im Projekt-Dashboard unterstützt:

• Ordner durchsuchen oder alle Dateien unterhalb eines Ordners anzeigen
• Dateien auswählen oder auf die Seite ziehen, um sie hochzuladen
• Nach Quelle filtern und die Dateien eines Runs oder einer Session aus deren Details öffnen
• Dateien und Ordner herunterladen, verschieben, umbenennen und löschen
• Die Metadaten einer Datei ansehen und bearbeiten

Abrechnung

Gespeicherte Dateien und heruntergeladene Bytes werden über das Projektguthaben abgerechnet. Dateien, die ein Agent mit den File Tools liest, zählen nicht als Download. Die Preise stehen auf der Preisseite.