Leitfaden zur Threads API

Ein Datensatz ist der digitale Eintrag für einen physischen Gegenstand – ein Asset, Bauteil, Dokument oder Workflow-Objekt. Er enthält einen Namen und eine Beschreibung, typisierte Felddaten, angehängte Dateien, verknüpfte Kennungen und einen Ereignisverlauf. Datensätze gehören einem Team, daher benötigt jede Anfrage ein Bearer-Token sowie den Header Dust-Ctx-Org-Id (und Dust-Ctx-Team-Id, um im Namen eines bestimmten Teams zu handeln) – siehe Authentifizierung und Konventionen.

Dieser Leitfaden behandelt die wichtigsten Abläufe. Informationen zu allen Parametern und Antwortschemas finden Sie in der API-Referenz.

Endpunkte im Überblick

Vorgang	Methode und Pfad
Einen oder mehrere Datensätze erstellen	`POST /api/v1/threads`
Datensätze auflisten/durchsuchen	`GET /api/v1/threads`
Datensätze zählen	`GET /api/v1/threads/count`
Einen Datensatz abrufen	`GET /api/v1/threads/{thread_id}`
Metadaten und Felder aktualisieren	`POST /api/v1/threads/{thread_id}`
Nur Felder aktualisieren	`POST /api/v1/threads/{thread_id}/data`
Archivierte Felddaten auflisten	`GET /api/v1/threads/{thread_id}/data/archived`
Archivierte Felddaten wiederherstellen	`POST /api/v1/threads/{thread_id}/data/restore`
Datensätze archivieren	`PATCH /api/v1/threads/archive`
Datensätze wiederherstellen	`PATCH /api/v1/threads/restore`
Berechtigungen des Aufrufers prüfen	`POST /api/v1/threads/permissions`
Anwesenheits-Heartbeat	`POST /api/v1/threads/{thread_id}/presence`
Dateien eines Datensatzes auflisten	`GET /api/v1/threads/{thread_id}/files`
Miniaturansicht festlegen/hochladen	`PATCH` / `POST /api/v1/threads/{thread_id}/thumbnail`

Bei Aktualisierungen der Miniaturansicht werden eine autorisierte resourceId oder eine inline eingebettete Base64-Rastergrafik als imageUri akzeptiert, die dekodiert höchstens 5 MiB groß sein darf. URLs zu externen Bildern werden abgelehnt. Datei-Uploads sind weiterhin über den Upload-Endpunkt für Miniaturansichten möglich. Auf Ressourcen basierende Miniaturansichten unterliegen den aktuellen Leseberechtigungen der Quellressource: Wenn der Zugriff verweigert wird oder die Quelle nicht mehr angehängt ist, enthalten Antworten sowohl für thumbnail als auch für thumbnailId den Wert null. Hochgeladene Miniaturansichten ohne Quellressource unterliegen der Sichtbarkeit des Datensatzes.

Einen Datensatz erstellen

POST /api/v1/threads akzeptiert drei durch type ausgewählte Formen des Anfragekörpers: single (ein Datensatz), list (mehrere normalisierte Datensätze) und raw (flache Schlüssel-Wert-Einträge). Alle drei akzeptieren eine optionale bundleId, um die Datensätze innerhalb eines Ordners zu erstellen.

curl
TypeScript

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 } }
    ]
  }'

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 } },
  ],
});

Feldwerte sind je nach Typ unter value verschachtelt – { "text": … }, { "number": … } und so weiter. Die Spezifikation definiert Eingaben für Text, Langtext, Zahlen, boolesche Werte, Datumsangaben, Datumsbereiche, Datum und Uhrzeit, Uhrzeiten, Zeitspannen, E-Mail-Adressen, Telefonnummern, URLs, JSON, Einfachauswahl, Mehrfachauswahl, Tags, Ressourcenverweise (Dateien) und Datensatzverweise.

Massenimport

Verwenden Sie type: "list", wenn Sie bereits über normalisierte { thread, data }-Objekte verfügen, oder type: "raw", um flache Einträge an die API zu übergeben. Sie leitet die Felder aus den Schlüssel-Wert-Paaren jedes Objekts ab und verwendet nameKey und descriptionKey (standardmäßig name / description) für die Metadaten des Datensatzes selbst:

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

Informationen zum atomaren Import vollständiger Baugruppenstrukturen finden Sie unter POST /api/v1/imports/plan und POST /api/v1/imports/commit in der Referenz.

Datensätze lesen

GET /api/v1/threads/{thread_id} gibt den Datensatz zusammen mit seinen Felddaten zurück (der optionale Abfrageparameter maxEvents schließt aktuelle Ereignisse ein). GET /api/v1/threads gibt eine Liste mit Cursor-Paginierung (cursor, pageSize, order, orderCol) zurück und unterstützt unter anderem folgende Filter:

Filter	Bedeutung
`q`, `queryCol`	Textsuche, optional auf eine Spalte beschränkt
`bundleId`	Datensätze in einem Ordner oder einer Kategorie
`templateId`	Aus einer Vorlage erstellte Datensätze
`tagType`	Datensätze, mit denen eine Kennung dieses Typs verknüpft ist
`hasResources`	Datensätze mit angehängten Dateien
`includeArchived`, `archivedOnly`	Sichtbarkeit archivierter Datensätze
`createdBy`, `ownedByTeam`	Herkunftsfilter
`excludeTransferred`, `transferredOnly`	Versendete Datensätze
`withActiveShipment`	Jeden Datensatz gegebenenfalls um seine aktive Sendung ergänzen

GET /api/v1/threads/count akzeptiert dieselben Filter und gibt nur die Anzahl zurück – nützlich für Dashboards und Paginierungsübersichten.

Einen Datensatz aktualisieren

Zwei Endpunkte für zwei unterschiedliche Zwecke:

POST /api/v1/threads/{thread_id} – akzeptiert { thread, update?, remove? }: Metadaten des Datensatzes (Name, Beschreibung, Vorlage, …) sowie optionale Feldänderungen in einem Aufruf.
POST /api/v1/threads/{thread_id}/data – nur Felder: { threadId, update, remove?, expectedUpdatedAt? }. Felder in update werden aktualisiert oder eingefügt (Zuordnung nach Name/ID); remove akzeptiert Feld-IDs.

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

Archivierte Felddaten

Beim Entfernen wird ein Feld archiviert, anstatt es zu löschen. GET /api/v1/threads/{thread_id}/data/archived listet archivierte Felder auf und POST /api/v1/threads/{thread_id}/data/restore stellt sie anhand ihrer ID wieder her ({ threadId, restore: ["field-id", …] }).

Datensätze archivieren und wiederherstellen

Die Archivierung erfolgt gesammelt und ist umkehrbar:

PATCH /api/v1/threads/archive – { threadIds: […], toggle? }. Mit toggle: true werden archivierte Datensätze in der Liste in einem einzigen Aufruf wieder aktiviert und aktive Datensätze archiviert.
PATCH /api/v1/threads/restore – archivierte Datensätze wiederherstellen.

Archivierte Datensätze erscheinen nicht in den standardmäßigen Listen. Verwenden Sie includeArchived oder archivedOnly, um sie anzuzeigen.

Berechtigungen

Bevor Sie Bearbeitungssteuerelemente darstellen oder Schreibvorgänge für mehrere Datensätze versuchen, sollten Sie abfragen, welche Aktionen der Aufrufer tatsächlich ausführen darf:

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 gibt für jeden Datensatz die effektiven Berechtigungen des Aufrufers im aktuellen Teamkontext zurück. Zugehörige Lesevorgänge sind GET /api/v1/threads/{thread_id}/access (welche Teams Zugriff gewähren) und GET /api/v1/threads/{thread_id}/shared (mit wem der Datensatz geteilt wird). Beide werden unter Teams, Freigaben und Verbindungen behandelt.

Anwesenheit

POST /api/v1/threads/{thread_id}/presence ist ein Heartbeat: Senden Sie ihn regelmäßig, während ein Benutzer einen Datensatz betrachtet (optional mit dem Anzeigenamen name / dem Bild image und beim Verlassen mit leaving: true). Die Antwort listet die Personen auf, die den Datensatz aktuell betrachten. DICE verwendet dies für die Anzeige „Wer ist noch hier?“.

Dateien und Miniaturansichten

Dateien werden über die Files API an Datensätze angehängt; die datensatzseitigen Lesevorgänge befinden sich hier:

GET /api/v1/threads/{thread_id}/files – die Dateien des Datensatzes, mit Cursor-Paginierung (includeArchived ist erforderlich).
GET /api/v1/threads/{thread_id}/files/{res_id} / POST …/files/{res_id} – eine einzelne angehängte Datei lesen und aktualisieren.
POST /api/v1/threads/{thread_id}/thumbnail – ein Bild hochladen (Multipart, Feld thumbnail) und es in einem Schritt als Miniaturansicht des Datensatzes festlegen.
PATCH /api/v1/threads/{thread_id}/thumbnail – die Miniaturansicht anhand einer vorhandenen Ressourcen-ID oder eines Bild-URI festlegen.

Kernmodell – wie Datensätze mit allem anderen zusammenhängen
Leitfaden zur Identifiers API – physische Kennungen mit Datensätzen verknüpfen
Leitfaden zur Files API – Uploads und Downloads
API-Referenz – vollständige Schemas für alle oben genannten Endpunkte

Ein Problem mit der Dokumentation melden