API-Schnellstart

Am Ende dieser Seite haben Sie einen API-Schlüssel gegen ein Bearer-Token ausgetauscht, die Organisation und das Team ermittelt, in denen Ihre Anmeldedaten agieren können, einen Datensatz erstellt und ihn samt Ereignisverlauf zurückgelesen.

Beide nachfolgenden Sprachvarianten sind vollständig und unabhängig voneinander: Alles wird definiert, bevor es verwendet wird, und keine übernimmt einen Schritt aus der anderen. Wählen Sie einen Tab aus und bleiben Sie darin.

Bevor Sie beginnen

Sie benötigen:

• Einen Service-Account-API-Schlüssel, der von einem Organisationsadministrator ausgestellt wurde. Persönliche API-Schlüssel gibt es nicht — siehe Authentifizierung und API-Schlüssel, falls Sie noch keinen besitzen.
• Der Service Account muss Mitglied des Teams sein, in das Sie schreiben. Das Erstellen von Datensätzen erfordert eine aktuelle Mitgliedschaft im ausgewählten Team; Anmeldedaten auf Organisationsebene, die keinem Team angehören, können /api/v1/me lesen, aber keine Datensätze erstellen. Bitten Sie Ihren Administrator, den Service Account einem Team hinzuzufügen, wenn Schritt 3 403 FORBIDDEN zurückgibt.
• curl-Variante: curl und jq (die Beispiele analysieren damit JSON; wenn Sie jq nicht installieren möchten, kopieren Sie die Werte manuell aus den Antworten).
• TypeScript-Variante: eine Laufzeitumgebung, die TypeScript direkt ausführt und über ein globales fetch verfügt — Node.js 22.18 oder neuer, Bun oder Deno. Führen Sie die Datei unter Node.js 18 oder 20 stattdessen mit einem Loader wie tsx aus. Es müssen keine Pakete installiert werden: Die Beispiele verwenden ausschließlich einfaches fetch. Ein typisierter Client ist separat verfügbar, siehe TypeScript-Client.

Dieser Code wird auf einem Server ausgeführt

Alles auf dieser Seite wird auf Ihrem Server oder Arbeitsplatzrechner ausgeführt. Ein API-Schlüssel und jedes daraus erzeugte Bearer-Token gewähren den vollständigen Zugriff des Service Accounts. Hinterlegen Sie keines von beiden jemals in Browser-JavaScript, einer mobilen Binärdatei, einer Clientvariablen zur Build-Zeit oder der Versionsverwaltung. Wenn ein Browser DUST-Daten scannen oder lesen muss, ruft er Ihr Backend auf, und Ihr Backend ruft die DUST API auf — siehe Anmeldedaten serverseitig aufbewahren.

Alle Anfragen werden an https://apid.dustid.io gesendet; die anderen Service-URLs finden Sie unter Umgebungen.

1. Umgebung einrichten

   curl

   export APID_URL="https://apid.dustid.io"
   export DUST_API_KEY="your-service-account-key"   # read this from your secrets manager

   TypeScript

   Speichern Sie die nachfolgende Datei als quickstart.ts und führen Sie sie mit node quickstart.ts, bun quickstart.ts oder deno run --allow-net --allow-env quickstart.ts aus. Jeder Schritt ergänzt dieselbe Datei.

   quickstart.ts

   // Makes the file an ES module, which is what lets the top-level `await`s
   // below run. (A `.mts` extension, or "type": "module" in package.json,
   // does the same job.)
   export {};
   
   const apidUrl = "https://apid.dustid.io";
   
   const apiKey = process.env.DUST_API_KEY;
   if (!apiKey) throw new Error("Set DUST_API_KEY in the environment.");

2. API-Schlüssel gegen ein Bearer-Token austauschen

   API-Schlüssel werden niemals an /api/v1/*-Endpunkte gesendet. Tauschen Sie den Schlüssel einmal über GET /api/auth/token aus, indem Sie ihn im Header x-api-key übergeben, und senden Sie das resultierende JWT bei jedem nachfolgenden Aufruf als Authorization: Bearer <token>.

   curl

   curl -fsS "$APID_URL/api/auth/token" -H "x-api-key: $DUST_API_KEY"

   { "token": "eyJhbGciOi...", "expiresIn": 900, "expiresAt": "2026-09-20T22:40:00.000Z" }

   export DUST_TOKEN="$(
     curl -fsS "$APID_URL/api/auth/token" -H "x-api-key: $DUST_API_KEY" | jq -r '.token'
   )"

   TypeScript

   quickstart.ts

   type TokenResponse = { token: string; expiresIn?: number; expiresAt?: string };
   
   async function exchangeToken(): Promise<TokenResponse> {
     const response = await fetch(`${apidUrl}/api/auth/token`, {
       headers: { "x-api-key": apiKey! },
     });
     if (!response.ok) {
       throw new Error(`Token exchange failed: ${response.status} ${await response.text()}`);
     }
     return (await response.json()) as TokenResponse;
   }
   
   const { token, expiresIn, expiresAt } = await exchangeToken();
   console.log(`Token valid for ${expiresIn ?? "unknown"}s (until ${expiresAt ?? "unknown"})`);

   Die Antwort enthält token sowie — sofern das JWT selbst einen Ablaufzeitpunkt enthält — expiresIn (verbleibende Sekunden) und expiresAt (ISO 8601). Lesen Sie die Gültigkeitsdauer aus der Antwort aus, anstatt sie fest im Code zu hinterlegen: Token sind derzeit kurzlebig (etwa 15 Minuten), und es gibt kein Refresh-Token. Ein lang laufender Auftrag muss den Austausch daher während der Ausführung erneut durchführen. Die vollständigen Regeln zur Gültigkeitsdauer, eine Caching-Implementierung und das Muster für eine einmalige Aktualisierung bei 401 finden Sie unter Authentifizierung → Token-Ablauf und -Aktualisierung.

3. Ihre Organisation ermitteln

   GET /api/v1/me ist einer der wenigen Endpunkte, die keine Kontext-Header benötigen. Er beschreibt die Anmeldedaten selbst: den Principal, die Organisationen, denen er angehört, und welche davon aktiv ist.

   curl

   curl -fsS "$APID_URL/api/v1/me" -H "Authorization: Bearer $DUST_TOKEN"

   {
     "userId": "6a1f…",
     "email": "sap-connector@example.com",
     "name": "SAP Connector",
     "activeOrganizationId": "b2c7…",
     "organizations": [
       { "id": "b2c7…", "name": "Anchor Electronics", "slug": "anchor-electronics", "roles": ["member"] }
     ]
   }

   # Prefer the active organization; fall back to the first membership.
   export DUST_ORG_ID="$(
     curl -fsS "$APID_URL/api/v1/me" -H "Authorization: Bearer $DUST_TOKEN" \
       | jq -er '.activeOrganizationId // .organizations[0].id'
   )"
   echo "Organization: $DUST_ORG_ID"

   TypeScript

   quickstart.ts

   type Organization = { id: string; name: string; slug: string; roles: string[] };
   type MeResponse = {
     userId: string;
     email: string;
     activeOrganizationId?: string | null;
     organizations: Organization[];
   };
   
   const auth = { Authorization: `Bearer ${token}` };
   
   const meResponse = await fetch(`${apidUrl}/api/v1/me`, { headers: auth });
   if (!meResponse.ok) {
     throw new Error(`/me failed: ${meResponse.status} ${await meResponse.text()}`);
   }
   const me = (await meResponse.json()) as MeResponse;
   
   const organizationId =
     me.activeOrganizationId ?? me.organizations[0]?.id;
   if (!organizationId) {
     throw new Error("This credential belongs to no organization — ask your admin.");
   }
   console.log(`Organization: ${organizationId}`);

   /me gibt Organisationen zurück, keine Teams

   Jeder Eintrag in organizations enthält genau id, name, slug und roles. Diese Antwort enthält keine Team-IDs — Teams werden separat im nächsten Schritt ermittelt. Wenn Ihre Anmeldedaten in mehr als einer Organisation agieren können, treffen Sie eine bewusste Auswahl, anstatt organizations[0] zu verwenden; bei einer falschen Auswahl wird unbemerkt in den falschen Mandanten geschrieben.

4. Ein Team auswählen (optional)

   Datensätze gehören zu einem Team innerhalb der Organisation. Sie haben zwei unterstützte Möglichkeiten:

   • Nichts unternehmen. Lassen Sie Dust-Ctx-Team-Id weg, und die API agiert im Stamm-Team der Organisation. Für eine Organisation mit nur einem Team ist das bereits der gesamte Schritt 4, und die Beispiele in Schritt 5 verwenden diesen Weg.
   • Ein Team angeben. GET /api/v1/teams listet die Teams auf, deren Mitglied Ihre Anmeldedaten sind, und zwar als { "teams": [ … ], "total": n }; jedes enthält teamId, orgId und name. Senden Sie das gewünschte Team als Dust-Ctx-Team-Id.
   curl

   curl -fsS "$APID_URL/api/v1/teams?pageSize=50" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     | jq '.teams[] | { teamId, name }'

   { "teamId": "b2c7…", "name": "Anchor Electronics" }
   { "teamId": "4e90…", "name": "Line 3 Receiving" }

   # Optional. Leave DUST_TEAM_ID unset to use the organization's root Team.
   export DUST_TEAM_ID="4e90…"

   Jede nachfolgende Anfrage übergibt -H "Dust-Ctx-Team-Id: ${DUST_TEAM_ID:-}". Ein leerer Wert wird genauso behandelt wie ein fehlender Header — es wird das Stamm-Team der Organisation verwendet. Daher funktioniert dasselbe Skript unabhängig davon, ob Sie die Variable festlegen.

   TypeScript

   quickstart.ts

   type Team = { teamId: string; orgId: string; name: string | null };
   
   const teamsResponse = await fetch(`${apidUrl}/api/v1/teams?pageSize=50`, {
     headers: { ...auth, "Dust-Ctx-Org-Id": organizationId },
   });
   if (!teamsResponse.ok) {
     throw new Error(`/teams failed: ${teamsResponse.status} ${await teamsResponse.text()}`);
   }
   const { teams } = (await teamsResponse.json()) as { teams: Team[]; total: number };
   for (const team of teams) console.log(`${team.teamId}  ${team.name ?? "(unnamed)"}`);
   
   // Optional. Leave DUST_TEAM_ID unset to act in the organization's root Team.
   const teamId = process.env.DUST_TEAM_ID;
   
   // Context headers for every call from here on. The Team header is present
   // only when a Team was chosen — an undefined value must not be sent.
   const context: Record<string, string> = {
     ...auth,
     "Dust-Ctx-Org-Id": organizationId,
     ...(teamId ? { "Dust-Ctx-Team-Id": teamId } : {}),
   };

   Grp bedeutet Team

   Dust-Ctx-Grp-Id ist die veraltete Schreibweise von Dust-Ctx-Team-Id und wird weiterhin akzeptiert (Dust-Ctx-Team-Id hat Vorrang, wenn beide gesendet werden). Die mit X- beginnenden Varianten beider Header funktionieren ebenfalls. Dies ist ausschließlich ein Alias für den Header — unter den Feldern des Anfragekörpers gibt es keine Entsprechung. Siehe Anfragekonventionen.

5. Einen Datensatz erstellen

   Ein Datensatz ist der Eintrag für ein einzelnes Asset oder Objekt. POST /api/v1/threads mit type: "single" erstellt einen Datensatz; thread.name ist das einzige Pflichtfeld, und das optionale Array data enthält typisierte Felder.

   curl

   curl -fsS "$APID_URL/api/v1/threads" \
     -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 '{
       "type": "single",
       "thread": {
         "name": "Tire SZ3J-11-ZJ17",
         "description": "Production asset"
       },
       "data": [
         { "name": "Serial Number", "type": "text",   "value": { "text": "SZ3J-11-ZJ17" } },
         { "name": "Max PSI",       "type": "number", "value": { "number": 51 } }
       ]
     }' | tee /tmp/created.json | jq '.created[0] | { threadId, name }'

   { "threadId": "0f13c0de-2f1a-4a2e-9f60-6d2f7b9f0a11", "name": "Tire SZ3J-11-ZJ17" }

   export THREAD_ID="$(jq -r '.created[0].threadId' /tmp/created.json)"

   TypeScript

   quickstart.ts

   type ThreadRecord = { threadId: string; name: string | null };
   
   const createResponse = await fetch(`${apidUrl}/api/v1/threads`, {
     method: "POST",
     headers: { ...context, "Content-Type": "application/json" },
     body: JSON.stringify({
       type: "single",
       thread: { name: "Tire SZ3J-11-ZJ17", description: "Production asset" },
       data: [
         { name: "Serial Number", type: "text", value: { text: "SZ3J-11-ZJ17" } },
         { name: "Max PSI", type: "number", value: { number: 51 } },
       ],
     }),
   });
   if (!createResponse.ok) {
     const error = await createResponse.json();
     throw new Error(`create failed: ${error.code} — ${error.message}`);
   }
   const { created } = (await createResponse.json()) as { created: ThreadRecord[] };
   const threadId = created[0]?.threadId;
   if (!threadId) throw new Error("The server created no Thread.");
   console.log(`Created ${threadId}`);

   Der Status lautet 201 Created, und der Antwortkörper hat die Form { "created": [ … ], "uploadResponses": [] } — eine Batch-Struktur, da derselbe Endpunkt mit type: "list" oder type: "raw" mehrere Datensätze gleichzeitig erstellt. Jeder Eintrag in created ist ein vollständiger Datensatz einschließlich seiner generierten threadId.

   Feldeinträge benötigen type und value; die Struktur von value richtet sich nach dem Typ: { "text": "…" } für text, { "number": 51 } für number. name ist die Bezeichnung des Feldes. Die vollständige Liste der Feldtypen finden Sie im Leitfaden zu Datensätzen.

6. Den Datensatz zurücklesen

   GET /api/v1/threads/{thread_id} gibt den Datensatz zusammen mit seinem Ereignisverlauf zurück — jeder Schreibvorgang wird erfasst, sodass die Audit-Trail bereits mit der Erstellung beginnt.

   curl

   curl -fsS "$APID_URL/api/v1/threads/$THREAD_ID" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Dust-Ctx-Team-Id: ${DUST_TEAM_ID:-}" \
     | jq '{ name: .thread.name, fields: [.thread.data[]?.name], events: (.events | length) }'

   { "name": "Tire SZ3J-11-ZJ17", "fields": ["Serial Number", "Max PSI"], "events": 1 }

   TypeScript

   quickstart.ts

   const getResponse = await fetch(`${apidUrl}/api/v1/threads/${threadId}`, {
     headers: context,
   });
   if (!getResponse.ok) {
     const error = await getResponse.json();
     throw new Error(`read failed: ${error.code} — ${error.message}`);
   }
   const record = (await getResponse.json()) as {
     thread: { name: string | null };
     events: unknown[];
   };
   console.log(record.thread.name);   // "Tire SZ3J-11-ZJ17"
   console.log(record.events.length); // at least 1 — creation is an event

   Die Antwort hat die Form { "thread": { … }, "events": [ … ] }. Die genaue Anzahl der Ereignisse ist nicht vertraglich festgelegt — rechnen Sie mit mindestens einem.

Wenn es nicht funktioniert hat

Was Sie gesehen haben	Was es bedeutet
401 UNAUTHORIZED beim Austausch	Der API-Schlüssel ist falsch, wurde widerrufen oder ist kein Service-Account-Schlüssel. Persönliche Schlüssel können nicht zur Authentifizierung verwendet werden.
401 UNAUTHORIZED bei einem /api/v1/*-Aufruf	Das Bearer-Token ist abgelaufen (diese Token sind kurzlebig). Tauschen Sie es erneut aus und wiederholen Sie den Aufruf einmal.
400 ORG_ID_REQUIRED	Sie haben Dust-Ctx-Org-Id bei einem organisationsbezogenen Endpunkt weggelassen.
400 INVALID_REQUEST mit Nennung eines Headers	Ein Kontext-Header war keine UUID. Header werden validiert, bevor der Endpunkt ausgeführt wird.
403 FORBIDDEN beim Erstellen	Der Service Account ist kein Mitglied des ausgewählten Teams. Bitten Sie Ihren Administrator, ihn hinzuzufügen.
404 beim Zurücklesen	In der Regel ist der Kontext falsch und der Datensatz fehlt nicht — ein Datensatz ist nur in der Organisation und dem Team sichtbar, denen er gehört oder mit denen er geteilt wurde.

Jeder Fehlerkörper hat die Form { code, message, status, detail? }, und jede Antwort enthält einen Header x-request-id, der protokolliert werden sollte. Die vollständige Codeliste, die Tabellen der Scanergebnisse und Hinweise zu Wiederholungsversuchen finden Sie unter Fehler und Scanergebnisse.

Nächste Schritte

• Anfragekonventionen — Kontext-Header, Paginierung und Lokalisierung.
• Fehler und Scanergebnisse — der vollständige Fehlervertrag.
• Datensätze — Feldtypen, Aktualisierungen, Archivierung, Auflistung und Suche.
• Kennungen — physische Kennungen mit Datensätzen verknüpfen und dagegen verifizieren (die Endpunkte /api/v1/tags/*).
• Dateien — Dateien mit Nachweisen an Datensätze anhängen.
• Teams und Freigabe — teamübergreifender Zugriff.
• TypeScript-Client — eine typisierte Alternative zu einfachem fetch.
• Vollständige API-Referenz — alle aus der OpenAPI-Spezifikation generierten Endpunkte. Der API-Server stellt außerdem selbst eine interaktive Referenz unter https://apid.dustid.io/api/docs und die Rohspezifikation unter /api/openapi.json bereit.