Data API

Anfragen

• Nur die eigenen Seiten der App können diese Pfade nutzen. Anfragen von anderen Websites lehnt connic mit 403 ab; maßgeblich sind die Header Origin und Sec-Fetch-Site, die Browser senden.
• Jede Anfrage außer GET, auch Lesezugriffe wie find, muss den Origin der App und content-type: application/json senden. Das gilt auch für Anfragen ohne Body, etwa um einen Run abzubrechen oder eine Session zu löschen.
• Bodys sind JSON-Objekte bis 1 MiB. Unbekannte Felder werden abgelehnt.
• Antworten sind JSON und werden nie gecacht. Fehler haben die Form {"error": "..."}; siehe Fehler.
• Verlangt die App eine Anmeldung, bekommt eine Anfrage ohne gültige Session ein 401. Schick den Besucher dann zu /_connic/login?return=<path>.

async function connic(path, body) {
  const response = await fetch(`/_connic/${path}`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body ?? {}),
  });
  if (response.status === 401) {
    location.assign(`/_connic/login?return=${encodeURIComponent(location.pathname)}`);
  }
  const result = await response.json();
  if (!response.ok) throw new Error(result.error);
  return result;
}

const { documents, total } = await connic("db/tickets/find", {
  filter: { status: "open" },
  sort: { _created_at: -1 },
  limit: 20,
});

Die Beispiele auf dieser Seite nutzen diese Hilfsfunktion connic().

Der Besucher

GET /_connic/me liefert den Besucher und die App. Dafür braucht es keine Regel. In einer öffentlichen App ist id die Besucher-ID des Browsers, email und name sind null, und signed_in ist false.

{
  "user": {
    "id": "8d2f6c1a-4b7e-4f0a-9c3d-2e5b7a9f1c64",
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "groups": ["support"],
    "signed_in": true
  },
  "app": {"key": "portal", "name": "Support portal"}
}

Datenbank

• Filter nutzen die Operatoren der Database Tools: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $and, $or, $not, $nor, $exists, $contains, $elemMatch, $regex und $near. Die Systemfelder heißen _id, _created_at und _updated_at.
• find liefert standardmäßig 25 Dokumente und mit limit bis zu 100. sort ordnet Feldern 1 oder -1 zu, skip blättert durch die Ergebnisse, und fields listet die Felder, die zurückkommen. count ist die Zahl der gelieferten Dokumente, total die Zahl der erlaubten Dokumente, die passen.
• update und delete brauchen einen nicht leeren filter. update setzt Felder der obersten Ebene und entfernt Felder mit null, wie db_update.
• Inserts bekommen die set-Felder der Regeln. inserted listet die gespeicherten Dokumente mit ihren Systemfeldern.

Dateien

• list zeigt einen Ordner: die Dateien, die der Besucher lesen darf, und die Unterordner mit lesbaren Dateien; siehe Ordner. Standard sind 25 Dateien, höchstens 100; übergib next_cursor als cursor für die nächste Seite. Filter nehmen die Operatoren der Datenbank auf _path, _folder, _name, _size, _mime_type, _created_at, _updated_at und Metadaten-Keys.
• update verschiebt oder benennt eine Datei mit new_path um und führt metadata mit den Metadaten der Datei zusammen; null entfernt einen Key. Das Verschieben auf einen belegten Pfad scheitert.
• Dateien haben die Felder, die unter Dateien beschrieben sind.

{
  "upload_id": "5f1d8a2c-7b3e-4c9a-a1d4-0e6b2f8c9d31",
  "path": "attachments/screenshot.png",
  "size": 48213,
  "part_bytes": 16777216,
  "part_count": 1,
  "upload_url": "/_connic/files/transfer/uploads/5f1d8a2c-7b3e-4c9a-a1d4-0e6b2f8c9d31",
  "token": "...",
  "expires_at": "2026-10-29T10:30:00+00:00"
}

const file = input.files[0];
const upload = await connic("files/upload", {
  path: `attachments/${file.name}`,
  size: file.size,
  metadata: { ticket_id: ticketId },
});
const token = encodeURIComponent(upload.token);
for (let part = 1; part <= upload.part_count; part++) {
  const start = (part - 1) * upload.part_bytes;
  await fetch(`${upload.upload_url}/parts/${part}?token=${token}`, {
    method: "PUT",
    body: file.slice(start, start + upload.part_bytes),
  });
}
const stored = await fetch(`${upload.upload_url}/complete?token=${token}`, { method: "POST" })
  .then((response) => response.json());

Verlangt die App eine Anmeldung, brauchen auch Übertragungen unter /_connic/files/transfer/ die Session des Besuchers.

Retrieval

const { results } = await connic("retrieval/search", {
  namespace: "help",
  query: "Wie ändere ich meine Rechnungsadresse?",
  limit: 5,
});

{
  "results": [
    {
      "entry_id": "invoice-address",
      "namespace": "help.billing",
      "content": "Um die Rechnungsadresse zu ändern, öffne die Einstellungen und wähle Abrechnung...",
      "score": 0.81,
      "metadata": {"title": "Rechnungsadresse ändern", "url": "https://help.example.com/billing/invoice-address"}
    }
  ]
}

• namespace muss ein Namespace aus access.retrieval sein oder darunter liegen. Die Suche umfasst diesen Namespace und alle Namespaces darunter, etwa help.billing bei einer Suche in help.
• query ist Text in natürlicher Sprache mit bis zu 1.000 Zeichen. limit ist standardmäßig 5 und höchstens 20. min_score, von 0 bis 1 und standardmäßig 0,3, lässt schwächere Treffer weg.
• Jedes Ergebnis ist eine passende Textstelle eines Eintrags: content ist ihr Text, score ihre Relevanz von 0 bis 1 und metadata die Metadaten des Eintrags, etwa ein Titel oder eine URL zum Verlinken.
• Wer einen Namespace durchsuchen darf, kann Inhalt und Metadaten jedes Eintrags darin lesen. Inhalte, die nicht jeder Besucher sehen darf, gehören in einen Namespace, den die App nicht nennt.
• Für eine Suche während der Eingabe warte, bis der Besucher eine Pause macht, bevor du suchst; siehe Limits.

Runs

{
  "id": "3c7e9a10-2f4b-4d8e-b6a1-9e0c5d2f7a48",
  "agent": "support",
  "status": "completed",
  "input": "{\"message\": \"Wo ist meine Bestellung?\"}",
  "output": "Deine Bestellung ist am Montag rausgegangen.",
  "error": null,
  "context": {"app": {"id": "…", "key": "portal"}, "end_user": {"id": "…", "signed_in": true}},
  "queued_at": "2026-10-29T09:12:03.120000Z",
  "started_at": "2026-10-29T09:12:03.410000Z",
  "ended_at": "2026-10-29T09:12:05.260000Z",
  "duration_ms": 1850
}

• Die Liste liefert standardmäßig 25 Runs und mit limit bis zu 100; übergib next_cursor als cursor für ältere Runs. status filtert nach einem Run-Status wie completed.
• input und output sind der gespeicherte Text. Parse ihn, wenn er JSON enthält.
• Die Statistik umfasst Runs, die in den letzten days UTC-Tagen in die Warteschlange kamen: statuses zählt Runs pro Status, und daily listet {day, runs} für jeden Tag.

Sessions

Eine Session ist der Gesprächsverlauf eines Agenten mit persistenter Session. Ihre ID lautet session-<agent>-<key>, wobei key der Wert von session.key des Agenten ist, etwa session-support-42 für Gespräch 42. session hat id, agent, state, created_at und updated_at; events listet die gespeicherten Ereignisse des Gesprächs.

Freigaben

{
  "id": "a8b1c2d3-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "run_id": "3c7e9a10-2f4b-4d8e-b6a1-9e0c5d2f7a48",
  "agent": "billing",
  "tool": "issue_refund",
  "params": {"order_id": "A-1042", "amount": 120},
  "message": "120 EUR für Bestellung A-1042 erstatten?",
  "response_label": null,
  "status": "pending",
  "created_at": "2026-10-29T09:14:00.000000Z",
  "resolved_at": null,
  "reason": null
}

approved ist true oder false, und message ist eine optionale Begründung. Freigaben, die eine Eingabe verlangen, erkennbar an response_label, brauchen zusätzlich response. connic hält den Besucher als Entscheider fest, mit E-Mail-Adresse, Name oder, bei öffentlichen Apps, dem Namen der App. Siehe Approvals.

Fehler

Limits

• Jeder Besucher kann pro Minute 300 Lese- und 60 Schreibanfragen sowie 30 Retrieval-Suchen senden. Angemeldete Besucher zählen pro Konto, öffentliche pro IP-Adresse.
• Jede App kann pro Minute 6.000 Lese- und 1.200 Schreibanfragen sowie 600 Retrieval-Suchen über alle Besucher annehmen.
• Listen liefern bis zu 100 Einträge pro Anfrage, Inserts nehmen bis zu 50 Dokumente, und Run-Statistiken umfassen bis zu 90 Tage.

Schreibzugriffe erscheinen im Audit Log des Projekts mit der App und der ID des Besuchers. Jede Anfrage zählt in den Statistiken der App als Datenanfrage, eine abgelehnte zusätzlich als abgelehnte Anfrage.