Skip to content

Thread Collaboration Full Lab ​

Ten steps. About forty-five minutes. Thread sharing, comments, and governance via curl.

This lab exercises GhostAI Thread Collaboration through the HTTP API as implemented in:

  • securechat/backend/app/routers/thread_sharing.py — prefix /api/threads, feature thread_collaboration
  • securechat/backend/app/routers/thread_comments.py — prefix /api/threads/{session_id}/comments, feature thread_collaboration_comments

You will create shares, list participants, accept invites, update roles and PII visibility, add threaded comments and resolve them, lock and unlock, fork, pin messages, read the audit trail, bulk share to a group and to an org role, and run shared-thread search.


Prerequisites ​

  • [ ] GhostAI backend reachable (e.g. http://localhost:8000)
  • [ ] Two API keys (or password flow) for User A (thread owner) and User B (invitee)—GhostAI user API keys typically look like gst_...
  • [ ] Feature thread_collaboration enabled for both users
  • [ ] Feature thread_collaboration_comments enabled for comment steps
  • [ ] A session_id for an existing chat thread owned by User A with several messages; note one message_id for anchoring comments and pins
  • [ ] Optional: a memory group_id and organization_id + org_role string valid in your tenant for bulk-share steps
  • [ ] curl, python3 -m json.tool (or jq)

Environment ​

bash
export BASE_URL="http://localhost:8000"
export API_KEY_A="gst_owner_key"
export API_KEY_B="gst_invitee_key"
export SESSION_ID="your-session-uuid"
export MESSAGE_ID="a-message-uuid-in-that-session"

Verify auth ​

bash
curl -s -H "Authorization: Bearer $API_KEY_A" "$BASE_URL/health" | python3 -m json.tool

Reference: Limits and policy ​

Constant / settingValue / values
MAX_PARTICIPANTS_PER_THREAD25
MAX_SHARES_PER_USER50
MAX_PENDING_INVITES_PER_HOUR5
thread_sharing_policy (org)platform_users (default), same_org, disabled
Share rolesviewer, commenter, collaborator, admin (hierarchy 0–3)
pii_visibilityfull, masked, redacted

Step 1: Create a share ​

Goal: POST /api/threads/{session_id}/share with email or user_id, role, PII visibility, and optional flags.

1.1 Share by email (pending invite if user not registered) ​

bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_A" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "colleague@example.com",
    "role": "commenter",
    "pii_visibility": "masked",
    "share_content_library": true,
    "share_memory": false,
    "can_export": false
  }' \
  "$BASE_URL/api/threads/$SESSION_ID/share" | python3 -m json.tool

1.2 Share by user_id (existing user) ​

bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_A" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "USER_B_UUID",
    "role": "collaborator",
    "pii_visibility": "redacted",
    "share_content_library": true,
    "share_memory": true,
    "can_export": false
  }' \
  "$BASE_URL/api/threads/$SESSION_ID/share" | python3 -m json.tool

Expected response shape (ShareResponse) ​

Fields include: id, session_id, target_type, user_id, shared_by, role, pii_visibility, invite_email, invite_token, invite_expires_at, status, share_content_library, share_memory, can_export, created_at, accepted_at.

Capture for later steps:

bash
export SHARE_ID="paste-share-uuid"
export INVITE_TOKEN="paste-invite-token-if-present"

Audit: share_created is logged. SIEM: collaboration.thread_shared when org context exists.


Step 2: List participants ​

Goal: GET /api/threads/{session_id}/participants

bash
curl -s -H "Authorization: Bearer $API_KEY_A" \
  "$BASE_URL/api/threads/$SESSION_ID/participants" | python3 -m json.tool

Returns an array of ParticipantResponse objects (user_id, email, display_name, role, pii_visibility, share_id, can_export).

User B can call the same endpoint after accepting (Step 3).


Step 3: Accept invite ​

Goal: POST /api/threads/accept-invite/{invite_token} as User B.

bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_B" \
  "$BASE_URL/api/threads/accept-invite/$INVITE_TOKEN" | python3 -m json.tool

Expected response ​

json
{
  "status": "accepted",
  "session_id": "...",
  "role": "commenter"
}

Audit: share_accepted.


Step 4: Update share role and PII visibility ​

Goal: PUT /api/threads/{session_id}/share/{share_id} (owner or admin participant only).

bash
curl -s -X PUT \
  -H "Authorization: Bearer $API_KEY_A" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "pii_visibility": "full",
    "share_memory": true,
    "can_export": true
  }' \
  "$BASE_URL/api/threads/$SESSION_ID/share/$SHARE_ID" | python3 -m json.tool

Omit fields you do not want to change. Audit: share_updated.

Revoke access (optional) ​

Skip this until the end of the lab if User B still needs access for Steps 5–10.

bash
curl -s -X DELETE \
  -H "Authorization: Bearer $API_KEY_A" \
  "$BASE_URL/api/threads/$SESSION_ID/share/$SHARE_ID" | python3 -m json.tool

Response: {"status": "revoked"}. Audit: share_revoked. SIEM: collaboration.share_revoked.


Step 5: Add comments and threaded replies ​

Goal: POST /api/threads/{session_id}/comments/ with optional message_id and parent_id.

5.1 Top-level comment anchored to a message ​

bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_B" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Please confirm this conclusion against the latest policy doc.",
    "message_id": "'"$MESSAGE_ID"'",
    "parent_id": null
  }' \
  "$BASE_URL/api/threads/$SESSION_ID/comments/" | python3 -m json.tool

Capture the new comment id:

bash
export COMMENT_ID="paste-comment-uuid"

Audit: comment_added.

5.2 Threaded reply (parent_id = parent comment id) ​

bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_A" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Confirmed — matches section 4.2 of the policy doc.",
    "message_id": "'"$MESSAGE_ID"'",
    "parent_id": "'"$COMMENT_ID"'"
  }' \
  "$BASE_URL/api/threads/$SESSION_ID/comments/" | python3 -m json.tool

5.3 List comments ​

All comments for the thread:

bash
curl -s -H "Authorization: Bearer $API_KEY_B" \
  "$BASE_URL/api/threads/$SESSION_ID/comments/" | python3 -m json.tool

Filter by message:

bash
curl -s -H "Authorization: Bearer $API_KEY_B" \
  "$BASE_URL/api/threads/$SESSION_ID/comments/?message_id=$MESSAGE_ID" | python3 -m json.tool

Dedicated message route:

bash
curl -s -H "Authorization: Bearer $API_KEY_B" \
  "$BASE_URL/api/threads/$SESSION_ID/comments/message/$MESSAGE_ID" | python3 -m json.tool

5.4 Edit (author only) ​

bash
curl -s -X PUT \
  -H "Authorization: Bearer $API_KEY_B" \
  -H "Content-Type: application/json" \
  -d '{"content": "Please confirm this conclusion against the latest policy doc (v2)."}' \
  "$BASE_URL/api/threads/$SESSION_ID/comments/$COMMENT_ID" | python3 -m json.tool

5.5 Resolve ​

bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_B" \
  "$BASE_URL/api/threads/$SESSION_ID/comments/$COMMENT_ID/resolve" | python3 -m json.tool

Response: {"status": "resolved"}. Audit: comment_resolved.

5.6 Soft delete ​

bash
curl -s -X DELETE \
  -H "Authorization: Bearer $API_KEY_B" \
  "$BASE_URL/api/threads/$SESSION_ID/comments/$COMMENT_ID" | python3 -m json.tool

Response: {"status": "deleted"}.


Step 6: Lock and unlock thread ​

Goal: POST /api/threads/{session_id}/lock and POST /api/threads/{session_id}/unlock (owner or admin share role).

bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_A" \
  "$BASE_URL/api/threads/$SESSION_ID/lock" | python3 -m json.tool
bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_A" \
  "$BASE_URL/api/threads/$SESSION_ID/unlock" | python3 -m json.tool

Responses: {"status": "locked"} / {"status": "unlocked"}. Audit: thread_locked, thread_unlocked.


Step 7: Fork thread ​

Goal: POST /api/threads/{session_id}/fork as user with collaborator or higher.

bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_B" \
  -H "Content-Type: application/json" \
  -d '{
    "fork_point_message_id": "'"$MESSAGE_ID"'",
    "title": "Fork — policy review branch"
  }' \
  "$BASE_URL/api/threads/$SESSION_ID/fork" | python3 -m json.tool

Expected shape (ForkThreadResponse) ​

Includes id (new session), user_id, title, organization_id, session_type, created_at, last_accessed, forked_from, fork_point_message_id, matter_id, memory_enabled, messages_copied.

Audit: thread_forked. SIEM: collaboration.thread_forked.


Step 8: Pin messages ​

Goal: POST /api/threads/{session_id}/pin, GET /api/threads/{session_id}/pins, DELETE /api/threads/{session_id}/pin/{pin_id} (collaborator+).

8.1 Pin with note ​

bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_B" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "'"$MESSAGE_ID"'",
    "note": "Legal approved — safe to share externally."
  }' \
  "$BASE_URL/api/threads/$SESSION_ID/pin" | python3 -m json.tool
bash
export PIN_ID="paste-pin-uuid"

Audit: message_pinned.

8.2 List pins ​

bash
curl -s -H "Authorization: Bearer $API_KEY_B" \
  "$BASE_URL/api/threads/$SESSION_ID/pins" | python3 -m json.tool

8.3 Unpin ​

bash
curl -s -X DELETE \
  -H "Authorization: Bearer $API_KEY_B" \
  "$BASE_URL/api/threads/$SESSION_ID/pin/$PIN_ID" | python3 -m json.tool

Audit: message_unpinned.


Step 9: Audit trail ​

Goal: GET /api/threads/{session_id}/audit (owner or admin only).

bash
curl -s -H "Authorization: Bearer $API_KEY_A" \
  "$BASE_URL/api/threads/$SESSION_ID/audit?limit=50&offset=0" | python3 -m json.tool

Filter by action:

bash
curl -s -H "Authorization: Bearer $API_KEY_A" \
  "$BASE_URL/api/threads/$SESSION_ID/audit?action=comment_added&limit=20" | python3 -m json.tool

You should see actions such as: share_created, share_updated, share_revoked, share_accepted, thread_locked, thread_unlocked, ownership_transferred, thread_forked, message_pinned, message_unpinned, comment_added, comment_resolved, bulk_share_group, bulk_share_role.

Ownership transfer (optional) ​

Only the thread owner may transfer to an admin participant:

bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_A" \
  -H "Content-Type: application/json" \
  -d '{"new_owner_id": "USER_B_UUID"}' \
  "$BASE_URL/api/threads/$SESSION_ID/transfer-ownership" | python3 -m json.tool

Audit: ownership_transferred.


Step 10: Bulk share and search shared threads ​

10.1 Bulk share by memory group ​

Goal: POST /api/threads/{session_id}/share-group (owner or admin).

bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_A" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "your-memory-group-uuid",
    "role": "viewer",
    "pii_visibility": "masked"
  }' \
  "$BASE_URL/api/threads/$SESSION_ID/share-group" | python3 -m json.tool

Response includes shared_count and shares. Audit: bulk_share_group.

10.2 Bulk share by organization role ​

Goal: POST /api/threads/{session_id}/share-role

bash
curl -s -X POST \
  -H "Authorization: Bearer $API_KEY_A" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "your-org-uuid",
    "org_role": "member",
    "share_role": "commenter",
    "pii_visibility": "redacted"
  }' \
  "$BASE_URL/api/threads/$SESSION_ID/share-role" | python3 -m json.tool

Audit: bulk_share_role.

10.3 List threads shared with the current user ​

bash
curl -s -H "Authorization: Bearer $API_KEY_B" \
  "$BASE_URL/api/threads/shared-with-me" | python3 -m json.tool

10.4 Search shared threads ​

Goal: GET /api/threads/search/shared?q=...

bash
curl -s -G \
  -H "Authorization: Bearer $API_KEY_B" \
  --data-urlencode "q=policy" \
  --data-urlencode "limit=20" \
  "$BASE_URL/api/threads/search/shared" | python3 -m json.tool

q is required, length 1–200; limit defaults to 20, max 100.


SIEM events (recap) ​

Emitted from thread sharing flows when organization context is available:

Event typeTypical trigger
collaboration.thread_sharedSuccessful POST .../share
collaboration.share_revokedDELETE .../share/{share_id}
collaboration.thread_forkedSuccessful POST .../fork
collaboration.ethical_wall_blockedShare blocked by ethical wall on matter

Appendix: WebSocket presence (optional) ​

Collaboration presence uses the same WebSocket endpoint as chat (e.g. /ws/chat with cookie auth in browsers). After connection, send JSON frames such as:

Subscribe to session

json
{ "type": "subscribe_session", "session_id": "YOUR_SESSION_ID" }

Typing

json
{ "type": "typing", "session_id": "YOUR_SESSION_ID", "is_typing": true }
json
{ "type": "typing", "session_id": "YOUR_SESSION_ID", "is_typing": false }

Server pushes include session_subscribed (with viewers), participant_joined, participant_left, typing, and typing_stopped.


Completion checklist ​

  • [ ] Created share with role and pii_visibility
  • [ ] Listed participants
  • [ ] Accepted invite as second user
  • [ ] Updated share via PUT
  • [ ] Created comment, reply, resolve, and optional soft delete
  • [ ] Locked and unlocked thread
  • [ ] Forked thread from a message
  • [ ] Pinned and unpinned a message
  • [ ] Retrieved audit log
  • [ ] Ran bulk share (group and/or org role) and shared-thread search

For a customer-facing walkthrough, use collaboration-demo-script.md.

SOC 2 Type II Certified | BAA Available | HIPAA-Ready