API quickstart

This guide takes you from an API key to a thread you created and read back, entirely over HTTPS. Every request below runs against the DUST API at https://apid.dustid.io; see Environments for all service URLs.

You will need a Service Account API key (created by an organization admin). If you don’t have one yet, start with Authentication and API keys.

1. Exchange your API key for a bearer token

   API keys are never sent to core endpoints directly. Exchange the key for a short-lived bearer token at GET /api/auth/token, passing the key in the x-api-key header:

   curl

   export APID_URL="https://apid.dustid.io"
   export DUST_API_KEY="your-service-account-key"
   
   export DUST_TOKEN="$(
     curl -fsS "$APID_URL/api/auth/token" \
       -H "x-api-key: $DUST_API_KEY" | jq -r '.token'
   )"

   TypeScript

   const apidUrl = "https://apid.dustid.io";
   
   const tokenResponse = await fetch(`${apidUrl}/api/auth/token`, {
     headers: { "x-api-key": process.env.DUST_API_KEY! },
   });
   const { token } = await tokenResponse.json();

   The response is a JSON object with a single token field — a JWT you send as Authorization: Bearer <token> on every /api/v1/* call. Tokens expire; re-run the exchange when they do. Details in Authentication.

2. Find your organization and team context

   Most endpoints run inside an organization and team, named by two request headers. GET /api/v1/me returns the organizations your credentials can act in:

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

   The response includes an organizations array (each with id, name, slug, roles) and an activeOrganizationId. Pick the organization you want to work in:

   export DUST_ORG_ID="<organization id from /api/v1/me>"
   # Optional: export DUST_TEAM_ID="<team id from /api/v1/me>" if you want a non-root team.

   Header	Required	Purpose
   Dust-Ctx-Org-Id	Yes, for org-scoped endpoints	Organization UUID.
   Dust-Ctx-Team-Id	No	Team UUID. Defaults to the organization root team.

   Grp means team

   Dust-Ctx-Grp-Id, the legacy spelling of Dust-Ctx-Team-Id, is still accepted — Grp/group is the legacy name for teams and survives in a few header and field names. See Request conventions for the full contract.

3. Create a thread

   A thread is the record for one asset or item; its data array holds typed fields. POST /api/v1/threads with type: "single" creates one:

   curl

   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",
         "description": "Production asset"
       },
       "data": [
         { "name": "Serial Number", "type": "text",   "value": { "text": "SZ3J-11-ZJ17" } },
         { "name": "Max PSI",       "type": "number", "value": { "number": 51 } }
       ]
     }'

   TypeScript

   import { ApidClient } from "@dustid/apid-client";
   
   const client = new ApidClient({
     baseUrl: apidUrl,
     bearerToken: token,
     organizationId,   // sent as Dust-Ctx-Org-Id
     teamId,           // optional; sent as Dust-Ctx-Team-Id when set
   });
   
   // createOne unwraps the batch response to the single created thread
   const created = await client.threads.createOne({
     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 } },
     ],
   });
   console.log(created.threadId);

   The raw response is 201 Created with { "created": [ ... ], "uploadResponses": [ ... ] }; each entry in created is the full thread record, including its generated threadId (a UUID). Field data entries require type and value; name labels the field.

4. Read it back

   GET /api/v1/threads/{thread_id} returns the thread plus its event history:

   curl

   export THREAD_ID="<created[0].threadId from the previous step>"
   
   curl -fsS "$APID_URL/api/v1/threads/$THREAD_ID" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"

   TypeScript

   const record = await client.threads.get(created.threadId);
   console.log(record.thread.name);       // "Tire SZ3J-11-ZJ17"
   console.log(record.events.length);     // creation events already recorded

   The response shape is { "thread": { ... }, "events": [ ... ] } — every write to a thread is recorded as an event, so the audit trail starts at creation.

5. Where to go next

   • Request conventions — context headers, error shape, pagination, localization.
   • Threads — field types, updates, archiving, listing and search.
   • Identifiers — bind and verify physical identifiers against threads (the /api/v1/tags/* endpoints).
   • Files — attach evidence files to threads.
   • Teams and sharing — cross-team access.
   • TypeScript client — the typed client used above.
   • Full API reference — every endpoint, generated from the live OpenAPI spec. The server also self-hosts an interactive reference at https://apid.dustid.io/api/docs and the raw spec at /api/openapi.json.