Développer avec des agents d’IA

Si vous utilisez un agent de programmation basé sur l’IA (Claude Code, Cursor, Copilot ou similaire) pour développer sur la plateforme DUST, cette page constitue son point d’entrée. Tout ce qui figure ici est accessible à une URL publique stable que vous pouvez transmettre à un agent.

Commencez ici

À fournir à votre agent	Pour
/skills/dice-api-integration/SKILL.md	Appeler l’API DUST : authentification, en-têtes de contexte, fiches, identifiants, fichiers, partage, expéditions
/skills/dust-go-connect-integration/SKILL.md	Ajouter le scan DUST à une application web s’exécutant dans l’application mobile DUST Go
/llms.txt	Une carte de toutes les pages, afin que l’agent puisse choisir ce dont il a besoin
/llms-full.txt	L’intégralité de la documentation dans un seul document en texte brut
/openapi.json	Le contrat exact des requêtes et des réponses

Les quatre faits sur lesquels les agents se trompent

Si vous ne fournissez rien d’autre au contexte de votre agent, fournissez-lui ces informations. Chacune correspond à une requête que l’API rejette, plutôt que de la tolérer silencieusement : toute erreur sur l’un de ces points fait donc échouer l’intégration.

1. Le champ de périmètre de recherche d’identification est searchTeamIds, un tableau JSON d’UUID d’équipes. Il n’existe aucun champ de requête searchGroupIds. Les charges utiles d’identification rejettent les propriétés non déclarées ; une orthographe incorrecte fait donc échouer toute la requête avec 400 INVALID_REQUEST. Le seul nom historique group encore pris en charge est l’en-tête Dust-Ctx-Grp-Id, accepté comme alias de Dust-Ctx-Team-Id.
2. Le champ tags est obligatoire pour la vérification et il s’agit d’un tableau d’objets : [{"tagId": "…", "tagType": "DUST"}], et non d’un tableau de chaînes d’identifiants. Dans les corps multiparties, il est encodé en JSON.
3. Une identification sans correspondance est une réponse accompagnée d’un statut d’erreur. 404 IDENTIFIER_NOT_FOUND signifie qu’aucune correspondance n’a été trouvée ; 503 SCAN_SEARCH_INCOMPLETE signifie que la recherche n’a pas pu être menée à son terme et doit être retentée ; 400 SCAN_LOW_KEYPOINTS signifie qu’un nouveau scan est nécessaire. Le code généré qui traite chaque réponse autre que 2xx comme une exception signale des indisponibilités qui n’ont jamais eu lieu. Le tableau canonique se trouve dans Erreurs et résultats de scan.
4. Les identifiants d’authentification restent sur le serveur. Un jeton porteur DUST confère l’intégralité des accès du compte de service et rien ne permet d’en réduire la portée pour une session de navigateur. L’architecture prise en charge est la suivante : navigateur → backend du client → API DUST. Ne générez jamais un composant qui reçoit un jeton DUST comme prop.

Exemples canoniques

Voici les structures à reproduire. Les deux blocs s’exécutent sur un serveur.

// Identify: which Thread does this capture belong to?
const form = new FormData();
form.set("tagType", "DUST");
form.set("data", captureBlob);                              // binary, not base64
form.set("searchTeamIds", JSON.stringify(allowedTeamIds));  // NOT searchGroupIds

const response = await fetch(`${apidUrl}/api/v1/tags/identify`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Dust-Ctx-Org-Id": organizationId,
    // "Dust-Ctx-Team-Id": teamId,  // optional; omit for the org's root Team
  },
  body: form,
});
const body = await response.json();

if (response.ok) {
  // body.type is "identified" | "matches" | "label"
} else if (body.code === "IDENTIFIER_NOT_FOUND") {
  // An answer: nothing matched. Not a failure.
} else if (body.code === "SCAN_SEARCH_INCOMPLETE") {
  // Retry — the item may well be enrolled.
}

// Verify: is this capture the item it claims to be?
const form = new FormData();
form.set("threadId", threadId);
form.set("tagType", "DUST");
form.set("data", captureBlob);
form.set("tags", JSON.stringify([{ tagId, tagType: "DUST" }])); // required, objects

const response = await fetch(`${apidUrl}/api/v1/tags/verify`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Dust-Ctx-Org-Id": organizationId },
  body: form,
});
const body = await response.json();

// One candidate: a mismatch is an error status.
// Two or more: a mismatch is HTTP 200 with { success: false } — read `success`.

Une séquence complète et exécutable de bout en bout (échange de jeton, découverte de l’organisation, découverte des équipes, création et relecture), sans aucune dépendance de paquet, est disponible dans le guide de démarrage rapide de l’API.

llms.txt

Conformément à la convention llms.txt, la racine du site fournit :

Fichier	Contenu
/llms.txt	Plan du site : chaque page accompagnée d’une description sur une ligne, ainsi que des liens vers la spécification OpenAPI, la référence interactive et les paquets npm
/llms-full.txt	Le contenu intégral de la documentation dans un seul document en texte brut
/llms-small.txt	Une variante minifiée pour les fenêtres de contexte plus petites

Indiquez /llms.txt à votre agent pour lui permettre de choisir les pages pertinentes, ou fournissez-lui /llms-full.txt lorsqu’il a besoin d’une vue complète. Les liens contenus dans les fichiers combinés sont des URL absolues qui renvoient vers la page et la section d’origine, afin qu’un agent puisse citer la source utilisée.

La spécification OpenAPI

La surface d’API faisant autorité est le document OpenAPI 3 :

• Version en direct depuis le serveur d’API : https://apid.dustid.io/api/openapi.json
• Copie générée lors de la compilation sur ce site : /openapi.json
• Référence interactive (Scalar) : https://apid.dustid.io/api/docs

La copie présente sur ce site correspond à la surface publique : les opérations internes à DUST en ont été retirées. Utilisez le document en direct lorsque vous devez vous assurer de décrire le serveur que vous appelez réellement.

Compétences d’intégration

Une compétence est un fichier Markdown unique au format SKILL.md (frontmatter YAML contenant name et description, suivi des instructions) qui enseigne à un agent une intégration complète de bout en bout : authentification, en-têtes, principaux flux et modes de défaillance. Les compétences sont autonomes : un agent ne disposant que du fichier de compétence peut mener à bien l’intégration.

dice-api-integrationS’authentifier (clé d’API → jeton porteur), définir les en-têtes de contexte et exécuter les principaux flux de l’API : créer des fiches, lier des identifiants, téléverser des fichiers, partager et expédier.TéléchargerCopier

dust-go-connect-integrationPermettre à une application web de scanner des identifiants DUST dans l’application mobile DUST Go au moyen de @dustid/dust-go-connect.TéléchargerCopier

Installer une compétence

1. Téléchargez le fichier de compétence depuis l’URL stable ci-dessus (par exemple, /skills/dice-api-integration/SKILL.md).

2. Pour Claude Code, placez-le dans .claude/skills/dice-api-integration/SKILL.md au sein de votre projet (le nom du répertoire correspond au champ name de la compétence). Claude le détecte automatiquement et le charge lorsque la tâche correspond.

3. Pour les autres agents, incluez le fichier dans le contexte ou le prompt système de l’agent : le fichier est en Markdown simple et autonome.

Ce que signifie, et ne signifie pas, « généré »

Chaque fichier de compétence contient un bloc de provenance indiquant la version de la documentation, la version de la spécification OpenAPI, le nombre de chemins qu’elle contient et une empreinte de la spécification publique exacte à partir de laquelle le fichier a été généré. Ces quatre informations permettent de déterminer l’époque de l’API décrite par votre copie et de savoir si deux copies proviennent de la même spécification.

Soyez précis quant à ce que cela vous garantit :

Partie d’une compétence	Origine	Ce qui peut devenir obsolète
L’index des points de terminaison dans dice-api-integration	Généré à partir de la spécification OpenAPI publique lors de la compilation	Rien : il reprend les chemins, méthodes et résumés de la spécification elle-même
Lignes de version et d’empreinte	Générées lors de la compilation	Rien
Tout le reste : instructions d’authentification, noms de paramètres, structures des charges utiles, comportement du SDK, gestion des erreurs	Rédigé manuellement	Tout élément modifié dans l’API sans mise à jour correspondante de la documentation

Une estampille de compilation n’est pas un résultat de test

Une bannière de version récente prouve que le fichier a été généré, et non que ses exemples ont été exécutés sur une API déployée. Considérez l’index généré des points de terminaison comme une aide à la découverte — la preuve qu’un chemin existe — et chaque exemple comme un élément à vérifier par rapport à la spécification OpenAPI ou dans un environnement de test jetable avant la mise en production. Si un exemple et la spécification sont en désaccord, la spécification prévaut ; merci également de nous le signaler afin que le texte puisse être corrigé.

Vérifier le code généré

Voici une courte liste de contrôle destinée à la personne qui examine le résultat produit par un agent :

• Chaque chemin et chaque méthode figurent dans la spécification. Aucun point de terminaison n’est inventé.
• Les appels à /api/v1/* comportent Authorization: Bearer ; tous ceux qui sont limités à une organisation comportent également Dust-Ctx-Org-Id.
• L’identification envoie searchTeamIds, jamais searchGroupIds.
• La vérification envoie tags sous la forme d’un tableau d’objets { tagId, tagType }.
• La gestion des erreurs effectue ses branchements selon code, jamais selon le texte de message, et distingue « aucune correspondance », « réessayer » et « effectuer un nouveau scan ».
• Aucune clé d’API ni aucun jeton porteur ne figure dans ce qui est livré à un navigateur ou à un client mobile.
• Les reçus de scan (scan.scanId, ou detail.scan.scanId en cas d’échec) sont consignés.
• Une réponse 401 déclenche une seule actualisation suivie d’une nouvelle tentative, et non une boucle.

Paquets npm

• @dustid/dust-go-connect — la passerelle de scan DUST destinée aux applications web (voir Intégrer DUST Go).
• @dustid/apid-client — le client d’API TypeScript typé. Indisponible dans le registre npm public ; consultez Client TypeScript pour connaître sa disponibilité et ses prérequis. Un agent ne doit pas générer de commande d’installation pour ce paquet.