Guide de l’API des fiches

Une fiche est l’enregistrement numérique d’un objet physique — un actif, une pièce, un document ou un élément de processus. Elle contient un nom et une description, des données de champ typées, des fichiers joints, des identifiants liés et un historique des événements. Les fiches appartiennent à une équipe ; chaque requête nécessite donc un jeton porteur ainsi que l’en-tête Dust-Ctx-Org-Id (et Dust-Ctx-Team-Id pour agir au nom d’une équipe précise) — consultez Authentification et Conventions.

Ce guide présente les principaux parcours. Pour connaître chaque paramètre et chaque schéma de réponse, consultez la référence de l’API.

Vue d’ensemble des points de terminaison

Opération	Méthode et chemin
Créer une ou plusieurs fiches	POST /api/v1/threads
Répertorier ou rechercher des fiches	GET /api/v1/threads
Compter les fiches	GET /api/v1/threads/count
Obtenir une fiche	GET /api/v1/threads/{thread_id}
Mettre à jour les métadonnées et les champs	POST /api/v1/threads/{thread_id}
Mettre à jour uniquement les champs	POST /api/v1/threads/{thread_id}/data
Répertorier les données de champ archivées	GET /api/v1/threads/{thread_id}/data/archived
Restaurer les données de champ archivées	POST /api/v1/threads/{thread_id}/data/restore
Archiver des fiches	PATCH /api/v1/threads/archive
Restaurer des fiches	PATCH /api/v1/threads/restore
Vérifier les autorisations de l’appelant	POST /api/v1/threads/permissions
Battement de présence	POST /api/v1/threads/{thread_id}/presence
Répertorier les fichiers d’une fiche	GET /api/v1/threads/{thread_id}/files
Définir ou téléverser la miniature	PATCH / POST /api/v1/threads/{thread_id}/thumbnail

Les mises à jour de miniature acceptent un resourceId autorisé ou un imageUri contenant en ligne une image matricielle encodée en base64, dont la taille décodée ne dépasse pas 5 Mio. Les URL d’images distantes sont refusées. Le téléversement de fichiers reste disponible par l’intermédiaire du point de terminaison de téléversement de miniature. Les miniatures adossées à une ressource suivent les autorisations de lecture actuelles de la ressource source : les réponses renvoient null pour thumbnail et thumbnailId lorsque l’accès est refusé ou que la source n’est plus jointe. Les miniatures téléversées sans ressource source suivent la visibilité de la fiche.

Créer une fiche

POST /api/v1/threads accepte trois formes de corps, sélectionnées par type : single (une fiche), list (plusieurs fiches normalisées) et raw (des enregistrements clé-valeur à plat). Les trois acceptent un bundleId facultatif permettant de créer les fiches dans un dossier.

curl

curl -fsS "$APID_URL/api/v1/threads" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "single",
    "thread": { "name": "Tire SZ3J-11-ZJ17" },
    "data": [
      { "name": "Serial Number", "type": "text", "value": { "text": "SZ3J-11-ZJ17" } },
      { "name": "Max PSI", "type": "number", "value": { "number": 51 } }
    ]
  }'

TypeScript

const created = await client.threads.create({
  type: "single",
  thread: { name: "Tire SZ3J-11-ZJ17" },
  data: [
    { name: "Serial Number", type: "text", value: { text: "SZ3J-11-ZJ17" } },
    { name: "Max PSI", type: "number", value: { number: 51 } },
  ],
});

Les valeurs de champ sont imbriquées sous value selon leur type — { "text": … }, { "number": … }, etc. La spécification définit les entrées pour le texte, le texte long, les nombres, les valeurs booléennes, les dates, les plages de dates, les dates-heures, les heures, les durées, les adresses e-mail, les numéros de téléphone, les URL, le JSON, les sélections simples, les sélections multiples, les balises, les références de ressources (fichiers) et les références de fiches.

Importation en masse

Utilisez type: "list" lorsque vous disposez déjà d’objets { thread, data } normalisés, ou type: "raw" pour transmettre à l’API des enregistrements à plat — elle déduit les champs des paires clé-valeur de chaque objet et utilise nameKey et descriptionKey (name / description par défaut) pour les métadonnées propres à la fiche :

{
  "type": "raw",
  "nameKey": "serial",
  "raw": [
    { "serial": "SZ3J-11-ZJ17", "part": "P355/30R19", "maxPsi": 51 }
  ]
}

Pour importer de manière atomique des structures d’assemblage complètes, consultez POST /api/v1/imports/plan et POST /api/v1/imports/commit dans la référence.

Consulter les fiches

GET /api/v1/threads/{thread_id} renvoie la fiche avec les données de ses champs (le paramètre de requête facultatif maxEvents inclut les événements récents). GET /api/v1/threads renvoie une liste avec une pagination par curseur (cursor, pageSize, order, orderCol) et prend notamment en charge les filtres suivants :

Filtre	Signification
q, queryCol	Recherche textuelle, éventuellement limitée à une colonne
bundleId	Fiches appartenant à un dossier ou à une catégorie
templateId	Fiches créées à partir d’un modèle
tagType	Fiches auxquelles est lié un identifiant de ce type
hasResources	Fiches comportant des fichiers joints
includeArchived, archivedOnly	Visibilité des archives
createdBy, ownedByTeam	Filtres de provenance
excludeTransferred, transferredOnly	Fiches expédiées ailleurs
withActiveShipment	Annoter chaque élément avec son expédition active, le cas échéant

GET /api/v1/threads/count accepte les mêmes filtres et renvoie uniquement le nombre de fiches — ce qui est utile pour les tableaux de bord et les résumés de pagination.

Mettre à jour une fiche

Deux points de terminaison, chacun ayant un objectif distinct :

• POST /api/v1/threads/{thread_id} — accepte { thread, update?, remove? } : les métadonnées de la fiche (nom, description, modèle, etc.) ainsi que les modifications facultatives des champs en un seul appel.
• POST /api/v1/threads/{thread_id}/data — uniquement les champs : { threadId, update, remove?, expectedUpdatedAt? }. Les champs de update sont insérés ou mis à jour (par correspondance de nom ou d’ID) ; remove accepte les ID des champs.

POST /api/v1/threads/{thread_id}/data

{
  "threadId": "9f6a…",
  "update": [
    { "name": "VIN", "type": "text", "value": { "text": "1HGCM82633A004352" } }
  ],
  "remove": []
}

Concurrence optimiste

Transmettez expectedUpdatedAt (la valeur updatedAt lue en dernier) lors des mises à jour de données. Si quelqu’un d’autre a modifié la fiche entre-temps, la requête échoue au lieu d’écraser silencieusement les modifications.

Données de champ archivées

La suppression d’un champ l’archive au lieu de le détruire. GET /api/v1/threads/{thread_id}/data/archived répertorie les champs archivés, et POST /api/v1/threads/{thread_id}/data/restore les restaure à partir de leur ID ({ threadId, restore: ["field-id", …] }).

Archiver et restaurer des fiches

L’archivage est une opération en masse et réversible :

• PATCH /api/v1/threads/archive — { threadIds: […], toggle? }. Avec toggle: true, les fiches archivées de la liste sont désarchivées et les fiches actives sont archivées en un seul appel.
• PATCH /api/v1/threads/restore — restaure les fiches archivées.

Les fiches archivées disparaissent des listes par défaut ; utilisez includeArchived ou archivedOnly pour les afficher.

Autorisations

Avant d’afficher des commandes de modification ou de tenter des écritures sur plusieurs fiches, déterminez ce que l’appelant est réellement autorisé à faire :

curl -fsS "$APID_URL/api/v1/threads/permissions" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{ "threadIds": ["9f6a…", "c2d1…"] }'

POST /api/v1/threads/permissions renvoie les autorisations effectives de l’appelant pour chaque fiche dans le contexte actuel de l’équipe. Lectures associées : GET /api/v1/threads/{thread_id}/access (les équipes qui accordent l’accès) et GET /api/v1/threads/{thread_id}/shared (les personnes avec lesquelles la fiche est partagée) — toutes deux présentées dans Équipes, partage et connexions.

Présence

POST /api/v1/threads/{thread_id}/presence est un battement : envoyez-le périodiquement pendant qu’un utilisateur consulte une fiche (éventuellement avec les informations d’affichage name / image, et leaving: true lorsqu’il quitte la fiche) ; la réponse répertorie les personnes qui consultent actuellement la fiche. DICE utilise ce mécanisme pour l’indicateur « qui d’autre est ici ».

Fichiers et miniatures

Les fichiers sont joints aux fiches par l’intermédiaire de l’API des fichiers ; les opérations de lecture côté fiche se trouvent ici :

• GET /api/v1/threads/{thread_id}/files — les fichiers de la fiche, paginés par curseur (includeArchived est obligatoire).
• GET /api/v1/threads/{thread_id}/files/{res_id} / POST …/files/{res_id} — consulter et mettre à jour un seul fichier joint.
• POST /api/v1/threads/{thread_id}/thumbnail — téléverser une image (requête multipart, champ thumbnail) et la définir comme miniature de la fiche en une seule étape.
• PATCH /api/v1/threads/{thread_id}/thumbnail — définir la miniature à partir de l’ID d’une ressource existante ou d’un URI d’image.

Pages associées

• Modèle fondamental — relations entre les fiches et tous les autres éléments
• Guide de l’API des identifiants — liaison d’identifiants physiques aux fiches
• Guide de l’API des fichiers — téléversements et téléchargements
• Référence de l’API — schémas complets de chaque point de terminaison présenté ci-dessus