API-Leitfaden für Teams, Freigaben und Verbindungen

Alles auf der DUST-Plattform gehört Teams und wird über sie aufgerufen. Dieser Leitfaden behandelt die vier Ebenen, die steuern, wer was sehen kann:

1. Kontext — für welche Organisation und welches Team eine Anfrage ausgeführt wird.
2. Freigaben — einem anderen Team Betrachter- oder Bearbeiterzugriff auf Datensätze und Ordner gewähren.
3. Verbindungen — die bestehende Vereinbarung zwischen zwei Teams (üblicherweise organisationsübergreifend), die Freigaben und Sendungen ermöglicht.
4. Sendungen und Aufteilungen — Datensätze über diese Grenzen hinweg übertragen oder daraus ableiten.

Vollständige Schemas: API-Referenz.

Anfragekontext

Identitäten werden in AuthD verwaltet; die Plattform-API grenzt jeden Aufruf mithilfe von Headern ein:

Authorization: Bearer <authd-token>
Dust-Ctx-Org-Id: <organization-uuid>
Dust-Ctx-Team-Id: <team-uuid>

Dust-Ctx-Org-Id ist für organisationsbezogene Aufrufe erforderlich. Dust-Ctx-Team-Id wählt das handelnde Team aus und verwendet standardmäßig das Stamm-Team der Organisation (Dust-Ctx-Grp-Id ist die akzeptierte veraltete Schreibweise). Siehe Authentifizierung und Konventionen.

• GET /api/v1/me — aktueller Benutzer, Sitzung, aktive Organisation und verfügbare Organisationen
• GET /api/v1/me/feature-flags — Funktionsschalter für den Aufrufer

Teams

Teams unterteilen eine Organisation; Datensätze, Ordner und Freigaben gehören jeweils zu einem Team. Beim Aktualisieren der Metadaten eines Teams bleiben seine Organisation und Team-ID erhalten; nicht deklarierte Aktualisierungseigenschaften werden abgelehnt.

Vorgang	Methode & Pfad
Für Sie sichtbare Teams auflisten	GET /api/v1/teams
Verbundene Partnerteams auflisten	GET /api/v1/teams/connected
Teams erstellen (Organisationsadministrator)	POST /api/v1/org/teams
Alle Teams der Organisation auflisten (Organisationsadministrator)	GET /api/v1/org/teams
Ein Team aktualisieren/löschen (Organisationsadministrator)	PATCH / DELETE /api/v1/org/teams/{team_id}
Mitgliedschaften hinzufügen oder aktualisieren (Organisationsadministrator)	POST /api/v1/org/teams/members
Mitgliedschaften auflisten/entfernen (Organisationsadministrator)	GET / DELETE /api/v1/org/teams/members

GET /api/v1/teams unterstützt q, role, rootId und includeLinked (um verbundene Partnerteams in Auswahllisten einzubeziehen). GET /api/v1/teams/connected listet die Partnerteams auf, die über aktive Verbindungen erreichbar sind — die zulässigen Empfänger für Freigaben und Sendungen.

Freigaben

Eine Freigabe gewährt einem Team Zugriff auf ein Objekt — einen Datensatz oder einen Ordner (Ordner/Kategorie) — als viewer oder editor. Berechtigungen werden als Beziehungstupel gespeichert, und Zugriff kann auch indirekt gewährt werden (ein freigegebener Ordner gibt seine Inhalte frei). Daher gibt es zwei Lesemodelle: die unverarbeitete Liste der Berechtigungen und die Zusammenfassung des effektiven Zugriffs.

curl

curl -fsS "$APID_URL/api/v1/sharing" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Dust-Ctx-Team-Id: $DUST_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "item": "thread", "id": "'"$THREAD_ID"'", "teamId": "'"$PARTNER_TEAM_ID"'", "relation": "viewer" }
    ]
  }'

TypeScript

await client.sharing.add({
  items: [
    { item: "thread", id: threadId, teamId: partnerTeamId, relation: "viewer" },
  ],
});

Vorgang	Methode & Pfad
Freigaben erstellen	POST /api/v1/sharing
Freigaben auflisten	GET /api/v1/sharing?direction=in|out
Beziehung einer Freigabe aktualisieren	PATCH /api/v1/sharing/{tuple_id}
Freigaben entfernen	DELETE /api/v1/sharing (Nutzdaten: { "ids": […] })
Effektiver Zugriff auf ein Objekt	GET /api/v1/sharing/access-summary?objectId=…&objectType=thread|bundle
Alles, was für einen Partner freigegeben wurde	GET /api/v1/sharing/partner-inventory?teamId=…

direction=out listet auf, was Ihr Team freigegeben hat; direction=in listet auf, was für Ihr Team freigegeben wurde. Die Zugriffszusammenfassung löst direkte Berechtigungen, die Vererbung von Ordnern und Teambeziehungen in die effektiven Berechtigungen für ein Objekt auf. Das Partnerinventar ist die Ansicht pro Verbindung — nützlich, bevor eine Verbindung pausiert oder geändert wird.

Komfortendpunkte auf Datensatzseite: GET /api/v1/threads/{thread_id}/shared (für wen dieser Datensatz freigegeben ist) und POST /api/v1/threads/permissions (was der Aufrufer tun kann) — siehe den Leitfaden zu Datensätzen.

Verbindungen

Eine Verbindung (API-Bezeichnung: team link) verbindet zwei Teams und regelt sämtliche teamübergreifenden Aktivitäten. Sie enthält eine zulässige Richtung des Datenflusses — send, receive oder send_receive, aus Sicht des anfragenden Teams ausgedrückt — und wird durch einen dreistufigen Handshake eingerichtet: Der Anfragende erstellt die Verknüpfung, der Partner akzeptiert sie und der Anfragende bestätigt sie. Verknüpfungen werden über ihren Einladungs-code adressiert.

Vorgang	Methode & Pfad
Erstellen (einladen)	POST /api/v1/connections — Nutzdaten { "allow": "send" | "receive" | "send_receive", "email"? }
Verbindungen auflisten	GET /api/v1/connections
Eine Verbindung abrufen/löschen	GET / DELETE /api/v1/connections/{code}
Akzeptieren (Partner)	PATCH /api/v1/connections/accept
Ablehnen (Partner)	PATCH /api/v1/connections/reject
Bestätigen (Anfragender)	PATCH /api/v1/connections/confirm
Abbrechen	PATCH /api/v1/connections/cancel
Pausieren/Fortsetzen	PATCH /api/v1/connections/pause / resume

Das Pausieren einer Verbindung setzt die davon abhängigen Freigabe- und Sendungsaktivitäten aus, ohne die Beziehung zu löschen.

Richtungsänderungen

Das Ändern der Richtung einer aktiven Verbindung erfordert ebenfalls einen Handshake, sodass keine Seite den Datenfluss einseitig ausweiten kann: Eines der Teams schlägt die Änderung vor, das andere Team akzeptiert sie und der Vorschlagende bestätigt sie. Bis zur Bestätigung bleibt die bisherige Richtung in Kraft:

• POST /api/v1/connections/amend/propose — Nutzdaten { "code", "allow" }
• PATCH /api/v1/connections/amend/accept / confirm / cancel

Freigaben, deren Datenfluss durch die neue Richtung nicht mehr zulässig ist, werden inaktiv, anstatt gelöscht zu werden.

Sendungen

Eine Sendung (API-Namensraum: /api/v1/transfers, veraltete Benennung) überträgt das Eigentum an Datensätzen auf ein verbundenes Team: Sie stellen einen Manifestentwurf zusammen, senden ihn und der Empfänger antwortet. Die Endpunkte in der Reihenfolge ihres Lebenszyklus:

Phase	Methode & Pfad
Entwurf erstellen	POST /api/v1/transfers
Manifesteinträge hinzufügen/aktualisieren/entfernen	POST /api/v1/transfers/{transfer_id}/items, PATCH / DELETE …/items/{item_id}
Primären Datensatz festlegen	PUT /api/v1/transfers/{transfer_id}/primary-thread
Senden	POST /api/v1/transfers/{transfer_id}/send
Vorschau anzeigen (Empfänger, nach dem Senden)	GET /api/v1/transfers/{transfer_id}/preview
Antworten: akzeptieren/ablehnen/Änderungen anfordern	POST /api/v1/transfers/{transfer_id}/respond
Nachrichten austauschen	POST /api/v1/transfers/{transfer_id}/messages
Abbrechen (Entwurf, gesendet oder Änderungen angefordert)	POST /api/v1/transfers/{transfer_id}/cancel
Fehlgeschlagene Sendung erneut versuchen	POST /api/v1/transfers/{transfer_id}/retry
Fehlgeschlagene Sendung aufgeben	POST /api/v1/transfers/{transfer_id}/abandon
Mit dem Manifest einer angehaltenen Sendung neu beginnen	POST /api/v1/transfers/{transfer_id}/start-from-prior-manifest
Auflisten (Postfachansichten)	GET /api/v1/transfers?box=inbox|outbox|sent
Eine Sendung mit ihrem Manifest abrufen	GET /api/v1/transfers/{transfer_id}

Für eine Antwort werden { "value": "accept" | "reject" | "request_changes" } übergeben (bei Änderungsanforderungen ist ein reason erforderlich). Die Auflistung unterstützt die Filter box, view, status und direction=inbound|outbound.

Hinweis

Diese Tabelle dient bewusst nur als Übersicht. Was ein Manifest enthält, wie die Offenlegung funktioniert und was die einzelnen Status bedeuten, wird unter Sendungen erläutert; das Herkunftsmodell hinter der teamübergreifenden Datensichtbarkeit wird unter Fabric beschrieben.

Aufteilungen

Eine Aufteilung leitet innerhalb Ihres eigenen Teams einen neuen Datensatz aus einem bestehenden ab — eine ausgewählte Teilmenge von Feldern, Dateien und Kennungen —, üblicherweise um genau das vorzubereiten, was Sie freigeben oder versenden möchten, während der Rest privat bleibt:

• POST /api/v1/slices — einen Datensatz aufteilen (bundleId zur Auswahl des Zielordners verwenden, fields auswählen, …)
• POST /api/v1/slices/batch — mehrere Datensätze in einem Vorgang ableiten
• GET /api/v1/slices/{slice_id} — eine Aufteilung mit ihren Fabric-Verknüpfungen

Verwandte Seiten

• Kernmodell — wie Teams, Freigaben und Verbindungen in das Domänenmodell passen
• Sendungen — Semantik des Sendungslebenszyklus
• Fabric — organisationsübergreifende Herkunft und Offenlegung
• API-Referenz — vollständige Schemas für jeden oben aufgeführten Endpunkt