Metadaten

metadata ist eine Menge eigener Schlüssel-Wert-Paare an einem Objekt: die ID des Datensatzes in Ihrem CRM, das Team, das dafür verantwortlich ist, der Synchronisierungslauf, der es geschrieben hat. Sursa speichert sie, gibt sie mit dem Objekt und in Ereignissen zurück und lässt Sie die Listen von Karten, Sammlungen und Ordnern danach filtern. Sursa interpretiert sie in keiner Weise.

{
  "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60",
  "title": "Refund policy",
  "metadata": {"crm_id": "A-1042", "team": "support"}
}

Objekte mit metadata: Karten, Sammlungen und Ordner. Auch ein Dokument einer benutzerdefinierten Quelle trägt metadata; daraus werden die metadata der Karte dieses Dokuments.

Limits

Eine Anfrage, die ein Limit verletzt, ergibt 400 mit dem Code api.metadata_invalid. error.details.key nennt den Schlüssel, und error.details.reason sagt, was falsch ist: too_many_keys, key_invalid, value_too_long, too_large oder value_invalid (der Wert ist keine Zeichenkette).

Werte sind Zeichenketten. Speichern Sie auch Zahlen und Datumsangaben als Zeichenketten, zum Beispiel "2026-10-24".

Metadaten setzen

Wenn Sie ein Objekt erstellen oder ersetzen (POST, PUT), wird metadata als Ganzes gesetzt:

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refund policy",
    "body": "Refunds are processed within 14 days.",
    "metadata": {"crm_id": "A-1042", "team": "support"}
  }'

In einer Anfrage mit multipart/form-data, etwa beim Hochladen einer Datei, senden Sie metadata als Formularfeld, dessen Wert das JSON-Objekt ist: metadata={"crm_id":"A-1042"}.

Metadaten aktualisieren

PATCH führt die gesendeten Schlüssel mit den vorhandenen zusammen. Ein Schlüssel mit dem Wert "" oder null wird entfernt; Schlüssel, die Sie nicht senden, bleiben unverändert:

curl -X PATCH https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"team": "billing", "legacy_flag": null}}'

{"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "metadata": {"crm_id": "A-1042", "team": "billing"}}

"metadata": {} ändert nichts. Um alle Paare zu entfernen, senden Sie jeden Schlüssel mit null.

Nach Metadaten filtern

Diese Listen akzeptieren metadata[<key>]=<value>:

• Karten: GET /v1/cards und GET /v1/cards/count;
• Sammlungen: GET /v1/collections;
• Ordner: GET /v1/folders und GET /v1/collections/{name}/folders.

Der Wert muss exakt übereinstimmen. Sie können bis zu 3 Bedingungen kombinieren, und ein Objekt muss alle erfüllen:

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "metadata[team]=support" \
  --data-urlencode "metadata[crm_id]=A-1042"

Mit einem Filter kommt ein Ordnerbaum als flache Liste: folders jeder Sammlung enthält die passenden Ordner mit leerem children, und parent_id zeigt, wo jeder davon liegt. GET /v1/folders lässt dann die Sammlungen ohne passende Ordner weg. Mehr als 3 Bedingungen oder ein ungültiger Schlüssel ergeben 400 mit dem Code api.metadata_invalid.

Was Metadaten nicht sind

• Kein Inhalt. Die Suche und die Antworten des Assistenten verwenden sie nicht. Was Menschen finden sollen, gehört in den Text der Karte, ihren Titel oder ihre Tags.
• Nicht privat. Alle, die das Objekt sehen können, sehen auch seine Metadaten. Speichern Sie darin nie Secrets, Tokens oder personenbezogene Daten, die die Leser des Objekts nicht sehen sollen.
• Kein Ersatz für external_id. Um eine Karte über die ID Ihres Datensatzes zu finden, geben Sie der Karte eine external_id; sie ist eindeutig, Metadatenwerte sind es nicht.