Sviluppare con agenti AI

Se utilizzi un agente AI di programmazione (Claude Code, Cursor, Copilot o simili) per sviluppare sulla piattaforma DUST, questa pagina è il suo punto di accesso. Tutto ciò che trovi qui è disponibile tramite un URL pubblico stabile che puoi fornire a un agente.

Inizia da qui

Fornisci al tuo agente	Per
/skills/dice-api-integration/SKILL.md	Chiamare l’API DUST: autenticazione, header di contesto, Schede, Identificatori, file, condivisione, Spedizioni
/skills/dust-go-connect-integration/SKILL.md	Aggiungere la scansione DUST a un’app web eseguita all’interno dell’app mobile DUST Go
/llms.txt	Una mappa di ogni pagina, affinché l’agente possa scegliere ciò che gli serve
/llms-full.txt	L’intera documentazione come singolo documento di testo semplice
/openapi.json	Il contratto esatto di richiesta e risposta

I quattro aspetti che gli agenti sbagliano

Se non inserisci altro nel contesto del tuo agente, inserisci almeno quanto segue. Ognuno di questi errori genera una richiesta che l’API rifiuta, anziché tollerarla silenziosamente; pertanto, commetterli impedisce del tutto il funzionamento dell’integrazione.

1. Il campo dell’ambito di ricerca per identify è searchTeamIds, un array JSON di UUID di Team. Non esiste alcun campo di richiesta searchGroupIds. I payload di identify rifiutano le proprietà non dichiarate, quindi l’ortografia errata fa fallire l’intera richiesta con 400 INVALID_REQUEST. L’unico nome legacy group ancora esistente è l’header Dust-Ctx-Grp-Id, accettato come alias di Dust-Ctx-Team-Id.
2. tags è obbligatorio per verify ed è un array di oggetti: [{"tagId": "…", "tagType": "DUST"}], non un array di stringhe ID. Nei body multipart è codificato come JSON.
3. Un identify non riuscito è una risposta con uno stato di errore. 404 IDENTIFIER_NOT_FOUND significa che non è stata trovata alcuna corrispondenza; 503 SCAN_SEARCH_INCOMPLETE significa che non è stato possibile completare la ricerca e che occorre riprovare; 400 SCAN_LOW_KEYPOINTS significa che occorre ripetere la scansione. Il codice generato che tratta ogni risposta non 2xx come un’eccezione segnala interruzioni del servizio che non si sono mai verificate. La tabella canonica è disponibile in Errori ed esiti delle scansioni.
4. Le credenziali rimangono sul server. Un bearer token DUST dispone dell’accesso completo del Service Account e nulla ne limita l’ambito per una sessione del browser. L’architettura supportata è browser → backend del cliente → API DUST. Non generare mai un componente che accetti un token DUST come prop.

Esempi canonici

Queste sono le strutture da copiare. Entrambi i blocchi vengono eseguiti su un server.

// 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`.

Una sequenza end-to-end completa ed eseguibile (scambio del token, individuazione dell’organizzazione, individuazione del Team, creazione, rilettura), priva di dipendenze da pacchetti, è disponibile nella guida introduttiva all’API.

llms.txt

Seguendo la convenzione llms.txt, la radice del sito rende disponibili:

File	Contenuto
/llms.txt	Mappa del sito: ogni pagina con una descrizione di una riga, oltre ai riferimenti alla specifica OpenAPI, alla documentazione di riferimento interattiva e ai pacchetti npm
/llms-full.txt	Il contenuto completo della documentazione come singolo documento di testo semplice
/llms-small.txt	Una variante ridotta per finestre di contesto più piccole

Indirizza il tuo agente a /llms.txt affinché possa scegliere le pagine, oppure forniscigli /llms-full.txt quando ha bisogno del quadro completo. I collegamenti all’interno dei file combinati sono URL assoluti che rimandano alla pagina e alla sezione di origine, così un agente può citare la fonte utilizzata.

La specifica OpenAPI

La descrizione autorevole dell’interfaccia API è il documento OpenAPI 3:

• Versione online dal server API: https://apid.dustid.io/api/openapi.json
• Una copia generata durante la build su questo sito: /openapi.json
• Documentazione di riferimento interattiva (Scalar): https://apid.dustid.io/api/docs

La copia presente su questo sito rappresenta l’interfaccia pubblica: le operazioni interne a DUST sono state rimosse. Utilizza il documento online quando devi avere la certezza di descrivere il server che stai effettivamente chiamando.

Skill di integrazione

Una skill è un singolo file Markdown nel formato SKILL.md (frontmatter YAML con name e description, seguito dalle istruzioni) che insegna a un agente un’intera integrazione end-to-end: autenticazione, header, flussi principali e modalità di errore. Le skill sono autosufficienti: un agente che dispone soltanto del file della skill può completare l’integrazione.

dice-api-integrationEsegue l’autenticazione (chiave API → bearer), imposta gli header di contesto e gestisce i flussi API principali: crea Schede, associa Identificatori, carica file, condivide ed effettua spedizioni.ScaricaCopia

dust-go-connect-integrationConsente a un’app web di scansionare Identificatori DUST all’interno dell’app mobile DUST Go tramite @dustid/dust-go-connect.ScaricaCopia

Installare una skill

1. Scarica il file della skill dall’URL stabile riportato sopra (ad es. /skills/dice-api-integration/SKILL.md).

2. Per Claude Code, inseriscilo in .claude/skills/dice-api-integration/SKILL.md all’interno del tuo progetto (il nome della directory corrisponde al valore name della skill). Claude lo rileva automaticamente e lo carica quando l’attività è pertinente.

3. Per gli altri agenti, includi il file nel contesto o nel prompt di sistema dell’agente: il file è in semplice formato Markdown ed è autosufficiente.

Cosa significa e cosa non significa «generato»

Ogni file di skill contiene un blocco di provenienza che indica la versione della documentazione, la versione della specifica OpenAPI, il numero di percorsi inclusi e un digest dell’esatta specifica pubblica sulla quale è stato generato il file. Questi quattro dati consentono di determinare quale generazione dell’API descrive la tua copia e se due copie provengono dalla stessa specifica.

Occorre essere precisi sui vantaggi che questo offre:

Parte di una skill	Origine	Cosa può diventare obsoleto
L’indice degli endpoint in dice-api-integration	Generato dalla specifica OpenAPI pubblica durante la build	Nulla: contiene i percorsi, i metodi e i riepiloghi della specifica stessa
Righe relative alla versione e al digest	Generate durante la build	Nulla
Tutto il resto: istruzioni per l’autenticazione, nomi dei parametri, strutture dei payload, comportamento dell’SDK, gestione degli errori	Scritto manualmente	Qualsiasi elemento modificato dall’API senza un corrispondente aggiornamento della documentazione

Un indicatore di build non è il risultato di un test

Un banner di versione recente dimostra che il file è stato generato, non che gli esempi al suo interno siano stati eseguiti su un’API distribuita. Considera l’indice degli endpoint generato come uno strumento di individuazione — la prova che un percorso esiste — e considera ogni esempio come qualcosa da verificare rispetto alla specifica OpenAPI o in un ambiente di test eliminabile prima del rilascio. Se un esempio e la specifica non concordano, prevale la specifica; segnalacelo anche, così potremo correggere il testo.

Controllare il codice generato

Un breve elenco di controllo per chi esamina il risultato prodotto da un agente:

• Ogni percorso e metodo compare nella specifica. Nessun endpoint inventato.
• Le chiamate /api/v1/* includono Authorization: Bearer; tutte quelle nell’ambito di un’organizzazione includono anche Dust-Ctx-Org-Id.
• Identify invia searchTeamIds, mai searchGroupIds.
• Verify invia tags come array di oggetti { tagId, tagType }.
• La gestione degli errori si dirama in base a code, mai in base al testo di message, e distingue tra «nessuna corrispondenza», «riprova» e «ripeti la scansione».
• Nessuna chiave API o bearer token compare in elementi distribuiti a un browser o a un client mobile.
• Le ricevute delle scansioni (scan.scanId oppure detail.scan.scanId in caso di errore) vengono registrate.
• 401 attiva un singolo aggiornamento e nuovo tentativo, non un ciclo.

Pacchetti npm

• @dustid/dust-go-connect — il bridge di scansione DUST Go per le app web (consulta Integrare con DUST Go).
• @dustid/apid-client — il client API TypeScript tipizzato. Non è disponibile nel registro npm pubblico; consulta Client TypeScript per disponibilità e prerequisiti. Un agente non deve generare un comando di installazione per questo pacchetto.