Sharing & collaboration

CRTX is multi-user. A collection has one owner and any number of members who joined via a share link. Sharing is deliberately simple: two permission levels, link-based invites, and the ability to hand a specific chat transcript to a teammate.

---

#Roles and permissions

Ownership-level actions (config changes, deleting documents, managing shares and members) remain owner-only regardless of a member's permission.

Admin note: the retrieval config endpoints (GET/PUT /collections/{id}/config) additionally require an admin flag (app_metadata.is_admin) on the user, so pipeline configuration can be gated to operators even among collection owners.

---

#Creating a share link

The owner generates a share, choosing whether recipients get query or ingest:

curl -X POST "$BASE_URL/collections/$COLLECTION_ID/shares" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "permission": "query" }'

The response includes a share_token. Turn it into an invite URL your app can open — the frontend handles this at /join/{token}:

https://your-app.com/join/<share_token>

Anyone with the link who is signed in can accept it.

---

#Accepting a share

curl -X POST "$BASE_URL/collections/join/$SHARE_TOKEN" \
  -H "Authorization: Bearer $TOKEN"

Behaviour:

• If the joiner is already the owner, they get { already_owner: true }.
• If they're already a member, they get their existing permission back (already_member: true) — links are idempotent.
• Otherwise they're added to collection_members with the share's permission.

Shared collections then appear in the joiner's GET /collections/ list, flagged with shared: true and their permission.

---

#Managing shares and members

# List active share links + current members (with emails)
GET  /collections/{id}/shares      # → { shares: [...], members: [...] }

# Revoke a share link (existing members keep access; the link stops working)
DELETE /collections/{id}/shares/{share_id}

# Remove a member entirely (also deletes their chat sessions/messages in this collection)
DELETE /collections/{id}/members/{member_id}

Removing a member is a hard removal: their sessions and messages scoped to that collection are deleted along with their membership.

---

#Sharing an individual chat

Beyond sharing a whole collection, an owner or member can hand a specific chat transcript to another member — useful for "here's the analysis I ran, take it from here."

# List members you can share a chat with (excludes yourself)
GET  /chat/{collection_id}/members            # → [{ user_id, email, role }]

# Copy a session (and all its messages + sources) to a target member
POST /chat/{collection_id}/sessions/{session_id}/share
     { "target_user_id": "<uuid>" }           # → { shared: true, new_session_id }

Rules:

• The target must already be a member of the collection (or the owner). You can't share a chat with someone who has no access to the underlying documents.
• Sharing copies the session into the recipient's account — they get their own editable copy, including the cited sources, not a live-linked view.
• target_user_id must be a valid UUID.

---

#Collaboration patterns

• Read-only distribution. Give a query link to a wide audience (a support team, a class, a department) so they can ask questions without risking the corpus. The owner curates what's in it.
• Shared contribution. Give an ingest link to a small trusted group that should keep the collection up to date (e.g. a docs team maintaining a knowledge base).
• Analyst handoff. An analyst runs a chat session against a collection, then shares that exact transcript (with sources) to a decision-maker who is already a member.
• Per-team collections. Because each collection is an isolated Pinecone namespace, giving each team its own collection keeps their content — and their quality metrics — cleanly separated.

Next: Business playbooks →