Appearance
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, featurethread_collaborationsecurechat/backend/app/routers/thread_comments.py— prefix/api/threads/{session_id}/comments, featurethread_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_collaborationenabled for both users - [ ] Feature
thread_collaboration_commentsenabled for comment steps - [ ] A
session_idfor an existing chat thread owned by User A with several messages; note onemessage_idfor anchoring comments and pins - [ ] Optional: a memory
group_idandorganization_id+org_rolestring valid in your tenant for bulk-share steps - [ ]
curl,python3 -m json.tool(orjq)
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.toolReference: Limits and policy
| Constant / setting | Value / values |
|---|---|
MAX_PARTICIPANTS_PER_THREAD | 25 |
MAX_SHARES_PER_USER | 50 |
MAX_PENDING_INVITES_PER_HOUR | 5 |
thread_sharing_policy (org) | platform_users (default), same_org, disabled |
| Share roles | viewer, commenter, collaborator, admin (hierarchy 0–3) |
pii_visibility | full, 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.tool1.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.toolExpected 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.toolReturns 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.toolExpected 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.toolOmit 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.toolResponse: {"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.toolCapture 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.tool5.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.toolFilter 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.toolDedicated message route:
bash
curl -s -H "Authorization: Bearer $API_KEY_B" \
"$BASE_URL/api/threads/$SESSION_ID/comments/message/$MESSAGE_ID" | python3 -m json.tool5.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.tool5.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.toolResponse: {"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.toolResponse: {"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.toolbash
curl -s -X POST \
-H "Authorization: Bearer $API_KEY_A" \
"$BASE_URL/api/threads/$SESSION_ID/unlock" | python3 -m json.toolResponses: {"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.toolExpected 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.toolbash
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.tool8.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.toolAudit: 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.toolFilter 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.toolYou 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.toolAudit: 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.toolResponse 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.toolAudit: 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.tool10.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.toolq 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 type | Typical trigger |
|---|---|
collaboration.thread_shared | Successful POST .../share |
collaboration.share_revoked | DELETE .../share/{share_id} |
collaboration.thread_forked | Successful POST .../fork |
collaboration.ethical_wall_blocked | Share 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.