Mit KI-Agenten entwickeln

Wenn Sie einen KI-Coding-Agenten (Claude Code, Cursor, Copilot oder Ähnliches) verwenden, um Anwendungen für die DUST-Plattform zu entwickeln, ist diese Seite sein Einstiegspunkt. Alles hier ist unter einer stabilen öffentlichen URL verfügbar, die Sie einem Agenten übergeben können.

Hier beginnen

Geben Sie Ihrem Agenten	Für
/skills/dice-api-integration/SKILL.md	Aufrufen der DUST API: Authentifizierung, Kontext-Header, Datensätze, Kennungen, Dateien, Freigaben, Sendungen
/skills/dust-go-connect-integration/SKILL.md	Hinzufügen von DUST-Scans zu einer Web-App, die innerhalb der mobilen DUST Go-App ausgeführt wird
/llms.txt	Eine Übersicht aller Seiten, damit der Agent auswählen kann, was er benötigt
/llms-full.txt	Die gesamte Dokumentation als ein einziges Klartextdokument
/openapi.json	Der exakte Vertrag für Anfragen und Antworten

Die vier Fakten, die Agenten falsch verstehen

Wenn Sie nichts anderes in den Kontext Ihres Agenten aufnehmen, nehmen Sie diese Punkte auf. Jeder einzelne betrifft eine Anfrage, die von der API abgelehnt und nicht stillschweigend toleriert wird. Ein Fehler hierbei lässt die Integration daher vollständig scheitern.

1. Das Feld für den Suchbereich bei Identify lautet searchTeamIds und ist ein JSON-Array aus Team-UUIDs. Es gibt kein Anfragefeld namens searchGroupIds. Identify-Nutzdaten lehnen nicht deklarierte Eigenschaften ab, sodass die falsche Schreibweise die gesamte Anfrage mit 400 INVALID_REQUEST scheitern lässt. Die einzige noch vorhandene veraltete Bezeichnung mit group ist der Header Dust-Ctx-Grp-Id, der als Alias für Dust-Ctx-Team-Id akzeptiert wird.
2. tags ist bei Verify erforderlich und ein Array aus Objekten: [{"tagId": "…", "tagType": "DUST"}], kein Array aus ID-Zeichenfolgen. In Multipart-Nutzdaten wird es JSON-kodiert.
3. Ein fehlgeschlagenes Identify ist eine Antwort mit einem Fehlerstatus. 404 IDENTIFIER_NOT_FOUND bedeutet, dass nichts übereinstimmte; 503 SCAN_SEARCH_INCOMPLETE bedeutet, dass die Suche nicht abgeschlossen werden konnte und wiederholt werden sollte; 400 SCAN_LOW_KEYPOINTS bedeutet, dass erneut gescannt werden muss. Generierter Code, der jede Nicht-2xx-Antwort als Ausnahme behandelt, meldet Ausfälle, die nie eingetreten sind. Die kanonische Tabelle finden Sie unter Fehler und Scanergebnisse.
4. Anmeldedaten verbleiben auf dem Server. Ein DUST-Bearer-Token umfasst den vollständigen Zugriff des Service Accounts, und es gibt keine Möglichkeit, diesen für eine Browsersitzung einzuschränken. Die unterstützte Architektur lautet: Browser → Kunden-Backend → DUST API. Generieren Sie niemals eine Komponente, die ein DUST-Token als Prop entgegennimmt.

Kanonische Beispiele

Diese Strukturen sollten Sie übernehmen. Beide Blöcke werden auf einem Server ausgeführt.

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

Eine vollständige, ausführbare End-to-End-Sequenz (Token-Austausch, Ermittlung der Organisation, Ermittlung des Teams, Erstellen, erneutes Lesen) ohne Paketabhängigkeiten finden Sie im API-Schnellstart.

llms.txt

Gemäß der llms.txt-Konvention stellt das Stammverzeichnis der Website Folgendes bereit:

Datei	Inhalt
/llms.txt	Sitemap: jede Seite mit einer einzeiligen Beschreibung sowie Verweise auf die OpenAPI-Spezifikation, die interaktive Referenz und die npm-Pakete
/llms-full.txt	Der vollständige Inhalt der Dokumentation als ein einziges Klartextdokument
/llms-small.txt	Eine minimierte Variante für kleinere Kontextfenster

Verweisen Sie Ihren Agenten auf /llms.txt, damit er die benötigten Seiten auswählen kann, oder stellen Sie ihm /llms-full.txt bereit, wenn er das Gesamtbild benötigt. Links in den zusammengefassten Dateien sind absolute URLs zu den jeweiligen Ursprungsseiten und -abschnitten, sodass ein Agent die verwendete Quelle angeben kann.

Die OpenAPI-Spezifikation

Die maßgebliche API-Oberfläche ist das OpenAPI-3-Dokument:

• Direkt vom API-Server: https://apid.dustid.io/api/openapi.json
• Eine beim Build erstellte Kopie auf dieser Website: /openapi.json
• Interaktive Referenz (Scalar): https://apid.dustid.io/api/docs

Die Kopie auf dieser Website bildet die öffentliche Oberfläche ab: DUST-interne Operationen wurden daraus entfernt. Verwenden Sie das Live-Dokument, wenn Sie sicherstellen müssen, dass Sie tatsächlich den Server beschreiben, den Sie aufrufen.

Integrations-Skills

Ein Skill ist eine einzelne Markdown-Datei im SKILL.md-Format (YAML-Frontmatter mit name und description, gefolgt von Anweisungen), die einem Agenten eine Integration von Anfang bis Ende vermittelt — Authentifizierung, Header, die zentralen Abläufe und die Fehlerfälle. Die Skills sind eigenständig: Ein Agent, dem nur die Skill-Datei zur Verfügung steht, kann die Integration vollständig umsetzen.

dice-api-integrationAuthentifizieren (API-Schlüssel → Bearer), Kontext-Header festlegen und die zentralen API-Abläufe ausführen: Datensätze erstellen, Kennungen verknüpfen, Dateien hochladen, freigeben und versenden.HerunterladenKopieren

dust-go-connect-integrationEiner Web-App ermöglichen, DUST-Kennungen innerhalb der mobilen DUST Go-App über @dustid/dust-go-connect zu scannen.HerunterladenKopieren

Einen Skill installieren

1. Laden Sie die Skill-Datei von der oben angegebenen stabilen URL herunter (z. B. /skills/dice-api-integration/SKILL.md).

2. Legen Sie sie für Claude Code in Ihrem Projekt unter .claude/skills/dice-api-integration/SKILL.md ab (der Verzeichnisname entspricht dem name des Skills). Claude erkennt sie automatisch und lädt sie, wenn die Aufgabe dazu passt.

3. Fügen Sie die Datei bei anderen Agenten dem Kontext oder System-Prompt des Agenten hinzu — die Datei besteht aus einfachem Markdown und ist eigenständig.

Was „generiert“ bedeutet und was nicht

Jede Skill-Datei enthält einen Herkunftsblock, der die Dokumentationsversion, die Version der OpenAPI-Spezifikation, die Anzahl der darin enthaltenen Pfade und einen Digest der exakten öffentlichen Spezifikation angibt, auf deren Grundlage die Datei erstellt wurde. Anhand dieser vier Angaben können Sie erkennen, welche API-Generation Ihre Kopie beschreibt und ob zwei Kopien aus derselben Spezifikation hervorgegangen sind.

Seien Sie präzise darin, was Ihnen das bietet:

Bestandteil eines Skills	Ursprung	Was veralten kann
Der Endpunktindex in dice-api-integration	Beim Build aus der öffentlichen OpenAPI-Spezifikation generiert	Nichts — es handelt sich um die Pfade, Methoden und Zusammenfassungen der Spezifikation selbst
Versions- und Digest-Zeilen	Beim Build generiert	Nichts
Alles Weitere: Anweisungen zur Authentifizierung, Parameternamen, Nutzdatenstrukturen, SDK-Verhalten, Fehlerbehandlung	Manuell verfasst	Alles, was die API ändert, ohne dass die Dokumentation entsprechend angepasst wird

Ein Build-Stempel ist kein Testergebnis

Ein aktuelles Versionsbanner weist nach, dass die Datei erstellt wurde, nicht dass die darin enthaltenen Beispiele mit einer bereitgestellten API ausgeführt wurden. Betrachten Sie den generierten Endpunktindex als Hilfsmittel zur Erkundung — als Nachweis dafür, dass ein Pfad existiert — und jedes Beispiel als etwas, das vor der Auslieferung anhand der OpenAPI-Spezifikation oder in einer temporären Testumgebung verifiziert werden muss. Falls ein Beispiel und die Spezifikation voneinander abweichen, ist die Spezifikation maßgeblich; teilen Sie uns dies bitte ebenfalls mit, damit der Text korrigiert werden kann.

Generierten Code prüfen

Eine kurze Prüfliste für Personen, die sich ansehen, was ein Agent erzeugt hat:

• Jeder Pfad und jede Methode ist in der Spezifikation enthalten. Keine erfundenen Endpunkte.
• Aufrufe von /api/v1/* enthalten Authorization: Bearer; jeder organisationsbezogene Aufruf enthält außerdem Dust-Ctx-Org-Id.
• Identify sendet searchTeamIds, niemals searchGroupIds.
• Verify sendet tags als Array aus { tagId, tagType }-Objekten.
• Die Fehlerbehandlung verzweigt anhand von code, niemals anhand des Texts in message, und unterscheidet zwischen „keine Übereinstimmung“, „erneut versuchen“ und „erneut scannen“.
• In Inhalten, die an einen Browser oder mobilen Client ausgeliefert werden, ist kein API-Schlüssel oder Bearer-Token enthalten.
• Scanbelege (scan.scanId oder bei einem Fehler detail.scan.scanId) werden erfasst.
• 401 löst genau eine Aktualisierung mit anschließendem Wiederholungsversuch aus, keine Schleife.

npm-Pakete

• @dustid/dust-go-connect — die DUST Go-Scanbrücke für Web-Apps (siehe Mit DUST Go integrieren).
• @dustid/apid-client — der typisierte TypeScript-API-Client. Nicht in der öffentlichen npm-Registry verfügbar; Informationen zur Verfügbarkeit und zu den Voraussetzungen finden Sie unter TypeScript-Client. Ein Agent sollte dafür keinen Installationsbefehl ausgeben.