Guide de l’API des équipes, du partage et des connexions

Tout ce qui se trouve sur la plateforme DUST appartient à des équipes et est accessible par leur intermédiaire. Ce guide présente les quatre couches qui déterminent qui peut voir quoi :

Contexte — l’organisation et l’équipe au nom desquelles une requête agit.
Partage — l’octroi à une autre équipe d’un accès en lecture ou en modification aux fiches et aux dossiers.
Connexions — l’accord permanent entre deux équipes (généralement de différentes organisations) qui permet le partage et les expéditions.
Expéditions et opérations Diviser — le déplacement ou la création dérivée de fiches au-delà de ces frontières.

Schémas complets : référence de l’API.

Contexte de la requête

L’identité réside dans AuthD ; l’API de la plateforme définit le périmètre de chaque appel à l’aide d’en-têtes :

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

Dust-Ctx-Org-Id est requis pour les appels limités au périmètre d’une organisation. Dust-Ctx-Team-Id sélectionne l’équipe agissante et prend par défaut l’équipe racine de l’organisation (Dust-Ctx-Grp-Id est l’ancienne graphie acceptée). Consultez Authentification et Conventions.

GET /api/v1/me — utilisateur actuel, session, organisation active et organisations disponibles
GET /api/v1/me/feature-flags — indicateurs de fonctionnalités de l’appelant

Équipes

Les équipes segmentent une organisation ; les fiches, les dossiers et les partages appartiennent tous à une équipe. La mise à jour des métadonnées d’une équipe conserve son organisation et son ID d’équipe ; les propriétés de mise à jour non déclarées sont rejetées.

Opération	Méthode et chemin
Répertorier les équipes que vous pouvez voir	`GET /api/v1/teams`
Répertorier les équipes partenaires connectées	`GET /api/v1/teams/connected`
Créer des équipes (administrateur de l’organisation)	`POST /api/v1/org/teams`
Répertorier toutes les équipes de l’organisation (administrateur de l’organisation)	`GET /api/v1/org/teams`
Mettre à jour/supprimer une équipe (administrateur de l’organisation)	`PATCH` / `DELETE /api/v1/org/teams/{team_id}`
Ajouter ou mettre à jour des appartenances (administrateur de l’organisation)	`POST /api/v1/org/teams/members`
Répertorier/supprimer des appartenances (administrateur de l’organisation)	`GET` / `DELETE /api/v1/org/teams/members`

GET /api/v1/teams prend en charge q, role, rootId et includeLinked (pour inclure les équipes partenaires connectées dans les sélecteurs). GET /api/v1/teams/connected répertorie les équipes partenaires accessibles par l’intermédiaire de connexions actives — le public valide pour les partages et les expéditions.

Un partage accorde à une équipe l’accès à un objet — une fiche ou un dossier (dossier/catégorie) — en tant que viewer ou editor. Les autorisations sont stockées sous forme de tuples de relation, et l’accès peut également être accordé indirectement (un dossier partagé donne accès à son contenu) ; il existe donc deux modèles de lecture : la liste brute des autorisations et le récapitulatif des accès effectifs.

curl
TypeScript

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" }
    ]
  }'

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

Opération	Méthode et chemin
Créer des partages	`POST /api/v1/sharing`
Répertorier les partages	`GET /api/v1/sharing?direction=in\|out`
Mettre à jour la relation d’un partage	`PATCH /api/v1/sharing/{tuple_id}`
Supprimer des partages	`DELETE /api/v1/sharing` (corps : `{ "ids": […] }`)
Accès effectif à un objet	`GET /api/v1/sharing/access-summary?objectId=…&objectType=thread\|bundle`
Tout ce qui est partagé avec un partenaire	`GET /api/v1/sharing/partner-inventory?teamId=…`

direction=out répertorie ce que votre équipe a partagé ; direction=in, ce qui a été partagé avec elle. Le récapitulatif des accès résout les autorisations directes, l’héritage des dossiers et les relations entre équipes pour déterminer les autorisations effectives sur un objet ; l’inventaire du partenaire fournit la vue propre à chaque connexion — utile avant de suspendre ou de modifier une connexion.

Raccourcis du côté des fiches : GET /api/v1/threads/{thread_id}/shared (avec qui cette fiche est partagée) et POST /api/v1/threads/permissions (ce que l’appelant peut faire) — consultez le guide des fiches.

Connexions

Une connexion (nom dans l’API : team link) relie deux équipes et contrôle toute activité entre elles. Elle comporte une direction autorisée pour le flux de données — send, receive ou send_receive, exprimée du point de vue de l’équipe à l’origine de la demande — et est établie par un échange en trois étapes : le demandeur crée le lien, le partenaire l’accepte, puis le demandeur le confirme. Les liens sont identifiés par leur code d’invitation.

Opération	Méthode et chemin
Créer (inviter)	`POST /api/v1/connections` — corps `{ "allow": "send" \| "receive" \| "send_receive", "email"? }`
Répertorier les connexions	`GET /api/v1/connections`
Obtenir/supprimer une connexion	`GET` / `DELETE /api/v1/connections/{code}`
Accepter (partenaire)	`PATCH /api/v1/connections/accept`
Refuser (partenaire)	`PATCH /api/v1/connections/reject`
Confirmer (demandeur)	`PATCH /api/v1/connections/confirm`
Annuler	`PATCH /api/v1/connections/cancel`
Suspendre/reprendre	`PATCH /api/v1/connections/pause` / `resume`

La suspension d’une connexion interrompt l’activité de partage et d’expédition qui en dépend sans supprimer la relation.

Modifications de direction

La modification de la direction d’une connexion active repose elle aussi sur un échange, de sorte qu’aucune partie ne puisse élargir unilatéralement le flux de données : l’une ou l’autre équipe fait une proposition, l’autre équipe l’accepte, puis l’équipe qui a fait la proposition la confirme ; l’ancienne direction reste en vigueur jusqu’à la confirmation :

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

Les partages dont le flux n’est plus autorisé par la nouvelle direction deviennent inactifs au lieu d’être supprimés.

Expéditions

Une expédition (espace de noms de l’API : /api/v1/transfers, dénomination historique) transfère la propriété de fiches à une équipe connectée : préparez un projet de manifeste, envoyez-le, puis le destinataire répond. Voici les points de terminaison, dans l’ordre du cycle de vie :

Étape	Méthode et chemin
Créer un projet	`POST /api/v1/transfers`
Ajouter/mettre à jour/supprimer des éléments du manifeste	`POST /api/v1/transfers/{transfer_id}/items`, `PATCH` / `DELETE …/items/{item_id}`
Définir la fiche principale	`PUT /api/v1/transfers/{transfer_id}/primary-thread`
Envoyer	`POST /api/v1/transfers/{transfer_id}/send`
Prévisualiser (destinataire, après l’envoi)	`GET /api/v1/transfers/{transfer_id}/preview`
Répondre : accepter/refuser/demander des modifications	`POST /api/v1/transfers/{transfer_id}/respond`
Échanger des messages	`POST /api/v1/transfers/{transfer_id}/messages`
Annuler (projet, envoyée ou avec modifications demandées)	`POST /api/v1/transfers/{transfer_id}/cancel`
Réessayer une expédition ayant échoué	`POST /api/v1/transfers/{transfer_id}/retry`
Abandonner une expédition ayant échoué	`POST /api/v1/transfers/{transfer_id}/abandon`
Recommencer à partir du manifeste d’une expédition arrêtée	`POST /api/v1/transfers/{transfer_id}/start-from-prior-manifest`
Répertorier (vues de boîte aux lettres)	`GET /api/v1/transfers?box=inbox\|outbox\|sent`
Obtenir une expédition avec son manifeste	`GET /api/v1/transfers/{transfer_id}`

La réponse prend la forme { "value": "accept" | "reject" | "request_changes" } (un reason est requis pour les demandes de modification). Le répertoriage prend en charge les filtres box, view, status et direction=inbound|outbound.

Diviser

Une opération Diviser crée une nouvelle fiche à partir d’une fiche existante au sein de votre propre équipe — à partir d’un sous-ensemble sélectionné de champs, de fichiers et d’identifiants — généralement pour préparer exactement ce que vous souhaitez partager ou expédier, tout en gardant le reste privé :

POST /api/v1/slices — diviser une fiche (choisissez le dossier cible avec bundleId, sélectionnez les fields, …)
POST /api/v1/slices/batch — créer plusieurs fiches dérivées en une seule opération
GET /api/v1/slices/{slice_id} — une opération Diviser avec ses liens Fabric

Modèle principal — comment les équipes, les partages et les connexions s’intègrent au domaine
Expéditions — sémantique du cycle de vie des expéditions
Fabric — provenance et divulgation interorganisations
Référence de l’API — schémas complets de chaque point de terminaison ci-dessus

Signaler un problème dans la documentation