Teams, sharing, and connections API guide

Everything in the DUST platform is owned and accessed by Teams. This guide covers the four layers that control who sees what:

1. Context — which Organization and Team a request acts as.
2. Sharing — granting another Team viewer or editor access to Threads and Folders.
3. Connections — the standing agreement between two Teams (usually across Organizations) that makes sharing and Shipments possible.
4. Shipments and Slices — moving or deriving records across those boundaries.

Full schemas: API reference.

Request context

Identity lives in AuthD; the platform API scopes each call with headers:

Authorization: Bearer <authd-token>
Dust-Ctx-Org-Id: <organization-uuid>
Dust-Ctx-Team-Id: <team-uuid>

Dust-Ctx-Org-Id is required for org-scoped calls. Dust-Ctx-Team-Id selects the acting Team and defaults to the Organization’s root Team (Dust-Ctx-Grp-Id is the accepted legacy spelling). See Authentication and Conventions.

• GET /api/v1/me — current user, session, active Organization, and available Organizations
• GET /api/v1/me/feature-flags — feature flags for the caller

Teams

Teams partition an Organization; Threads, Folders, and shares all belong to a Team.

Operation	Method & path
List Teams you can see	GET /api/v1/teams
List connected partner Teams	GET /api/v1/teams/connected
Create Teams (org admin)	POST /api/v1/org/teams
List all Teams in the Organization (org admin)	GET /api/v1/org/teams
Update / delete a Team (org admin)	PATCH / DELETE /api/v1/org/teams/{team_id}
Add or update memberships (org admin)	POST /api/v1/org/teams/members
List / remove memberships (org admin)	GET / DELETE /api/v1/org/teams/members

GET /api/v1/teams supports q, role, rootId, and includeLinked (to include connected partner Teams in pickers). GET /api/v1/teams/connected lists the partner Teams reachable through active Connections — the valid audience for sharing and Shipments.

Sharing

A share grants one Team access to one object — a Thread or a bundle (Folder/Category) — as viewer or editor. Grants are stored as relationship tuples, and access can also arrive indirectly (a shared Folder conveys its contents), so there are two read models: the raw grant list, and the effective access summary.

curl

curl -fsS "$APID_URL/api/v1/sharing" \
  -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 '{
    "items": [
      { "item": "thread", "id": "'"$THREAD_ID"'", "teamId": "'"$PARTNER_TEAM_ID"'", "relation": "viewer" }
    ]
  }'

TypeScript

await client.sharing.add({
  items: [
    { item: "thread", id: threadId, teamId: partnerTeamId, relation: "viewer" },
  ],
});

Operation	Method & path
Create shares	POST /api/v1/sharing
List shares	GET /api/v1/sharing?direction=in|out
Update a share’s relation	PATCH /api/v1/sharing/{tuple_id}
Remove shares	DELETE /api/v1/sharing (body: { "ids": […] })
Effective access for one object	GET /api/v1/sharing/access-summary?objectId=…&objectType=thread|bundle
Everything shared with one partner	GET /api/v1/sharing/partner-inventory?teamId=…

direction=out lists what your Team has shared; direction=in what has been shared with it. The access summary resolves direct grants, Folder inheritance, and Team relationships into the effective permissions for an object; partner inventory is the per-Connection view — useful before pausing or amending a Connection.

Thread-side conveniences: GET /api/v1/threads/{thread_id}/shared (who this Thread is shared with) and POST /api/v1/threads/permissions (what the caller can do) — see the Threads guide.

Connections

A Connection (API name: team link) connects two Teams and gates all cross-Team activity. It carries an allowed data-flow direction — send, receive, or send_receive, expressed from the requesting Team’s perspective — and is established by a three-step handshake: the requester creates the link, the partner accepts it, and the requester confirms. Links are addressed by their invite code.

Operation	Method & path
Create (invite)	POST /api/v1/connections — body { "allow": "send" | "receive" | "send_receive", "email"? }
List Connections	GET /api/v1/connections
Get / delete one	GET / DELETE /api/v1/connections/{code}
Accept (partner)	PATCH /api/v1/connections/accept
Reject (partner)	PATCH /api/v1/connections/reject
Confirm (requester)	PATCH /api/v1/connections/confirm
Cancel	PATCH /api/v1/connections/cancel
Pause / resume	PATCH /api/v1/connections/pause / resume

Pausing a Connection suspends the sharing and Shipment activity that depends on it without deleting the relationship.

Direction amendments

Changing an active Connection’s direction is itself a handshake, so neither side can unilaterally widen data flow — either Team proposes, the other Team accepts, and the proposer confirms; the old direction stays in force until confirmation:

• POST /api/v1/connections/amend/propose — body { "code", "allow" }
• PATCH /api/v1/connections/amend/accept / confirm / cancel

Shares whose flow the new direction no longer permits become dormant rather than being deleted.

Shipments

A Shipment (API namespace: /api/v1/transfers, legacy naming) transfers ownership of Threads to a connected Team: assemble a draft manifest, send it, and the receiver responds. The endpoints, in lifecycle order:

Stage	Method & path
Create draft	POST /api/v1/transfers
Add / update / remove manifest items	POST /api/v1/transfers/{transfer_id}/items, PATCH / DELETE …/items/{item_id}
Set primary Thread	PUT /api/v1/transfers/{transfer_id}/primary-thread
Send	POST /api/v1/transfers/{transfer_id}/send
Preview (receiver, after send)	GET /api/v1/transfers/{transfer_id}/preview
Respond: accept / reject / request changes	POST /api/v1/transfers/{transfer_id}/respond
Converse	POST /api/v1/transfers/{transfer_id}/messages
Cancel (draft, sent, or change-requested)	POST /api/v1/transfers/{transfer_id}/cancel
Retry a failed Shipment	POST /api/v1/transfers/{transfer_id}/retry
Abandon a failed Shipment	POST /api/v1/transfers/{transfer_id}/abandon
Restart from a stopped Shipment’s manifest	POST /api/v1/transfers/{transfer_id}/start-from-prior-manifest
List (mail-box views)	GET /api/v1/transfers?box=inbox|outbox|sent
Get one with its manifest	GET /api/v1/transfers/{transfer_id}

Responding takes { "value": "accept" | "reject" | "request_changes" } (a reason is required for change requests). Listing supports box, view, status, and direction=inbound|outbound filters.

Note

This table is deliberately just a map. What a manifest contains, how disclosure works, and what each status means are covered in Shipments; the provenance model behind cross-Team data visibility is Fabric.

Slices

A Slice derives a new Thread from an existing one within your own Team — a selected subset of fields, files, and identifiers — typically to prepare exactly what you intend to share or ship, keeping the rest private:

• POST /api/v1/slices — slice one Thread (choose target Folder via bundleId, select fields, …)
• POST /api/v1/slices/batch — derive many Threads in one operation
• GET /api/v1/slices/{slice_id} — a Slice with its Fabric links

Related pages

• Core model — how Teams, shares, and Connections fit the domain
• Shipments — Shipment lifecycle semantics
• Fabric — cross-organization provenance and disclosure
• API reference — full schemas for every endpoint above