Appearance
Content Library Full Lab
Ten steps. Forty-five minutes. Grants, hybrid search, versions, and audit — entirely through the API.
This lab exercises the Content Library as an admin or power user with appropriate RBAC. You will use curl against http://localhost:8000 (or your deployed host). All routes live under the prefix /api/content-library.
Scenario
You are the knowledge admin for Northwind Analytics. You must verify users can only see granted content, upload a runbook with a second revision and diff, delegate access with templates, curate a collection, prove hybrid search, export audits, register an external sync source, and read analytics including stale documents.
Prerequisites
- [ ] Backend running (
cd securechat/backend && uvicorn app.main:app --reload --port 8000) - [ ] Organization has Content Library entitlement (Team tier or higher)
- [ ] API token with at least:
content_library:read— steps 1–2, 6–7 (partial)content_library:manage— uploads, grants, collections, sourcescontent_library:audit— audit, analytics, stale, feedback list
- [ ]
curl,python3 -m json.tool, andjqinstalled (brew install jqon macOS) - [ ] A target user ID in the same organization (for grants). Resolve with:
bash
export GHOSTAI_API_KEY="gst_your_token"
export BASE_URL="http://localhost:8000"
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
"$BASE_URL/api/auth/me" | jq '.id, .email'Save the UUID as TARGET_USER_ID.
Environment shortcuts
bash
export GHOSTAI_API_KEY="gst_your_admin_token"
export BASE_URL="http://localhost:8000"
export HDR=(-H "Authorization: Bearer $GHOSTAI_API_KEY" -H "Content-Type: application/json")For multipart uploads, omit Content-Type: application/json on the upload request so curl sets the boundary.
Step 1: Access Check
Duration: 3 minutes
Goal: Confirm the token can use the library gate before deeper calls.
1.1 Lightweight access probe
bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/access-check" | python3 -m json.toolExpected: "has_access": true if you have content_library:read and at least one active grant (or you are a platform admin). If false, add a grant in Step 5 first using a higher-privilege flow, or ask an owner to grant you a category.
1.2 Quota baseline
bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/quota" | python3 -m json.toolExpected: total_bytes, item_count (or equivalent usage fields), and quota_bytes": 10737418240 (10 GiB).
Step 2: Browse Categories and Items
Duration: 5 minutes
Goal: Navigate metadata the same way the UI does.
2.1 List categories
bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/categories" | python3 -m json.tool2.2 Subcategories for one category
Replace engineering with a category returned above.
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/subcategories?category=engineering" | python3 -m json.tool2.3 List items (optional filters)
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/items?category=engineering" | python3 -m json.toolWith text filter:
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/items?search=runbook" | python3 -m json.tool2.4 Recommendations and recent
bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/recommended" | python3 -m json.tool
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/recent" | python3 -m json.toolExpected: JSON arrays shaped for the UI; empty arrays are valid on a fresh org.
Step 3: Upload a Document
Duration: 5 minutes
Goal: Create a new library item via multipart upload.
Create a small file:
bash
cat > /tmp/northwind-runbook-v1.md << 'EOF'
# Northwind API Runbook
## Overview
Primary API cluster runs in us-east-1.
## Escalation
Page the on-call via PagerDuty service API-PROD.
EOFUpload (content_library:manage required). One request — print and capture the item id:
bash
RESP=$(curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
-F "file=@/tmp/northwind-runbook-v1.md" \
"$BASE_URL/api/content-library/items/upload?category=engineering&description=Northwind%20API%20operations%20runbook")
echo "$RESP" | python3 -m json.tool
export ITEM_ID=$(echo "$RESP" | jq -r '.id')
echo "ITEM_ID=$ITEM_ID"If the file already exists at the same path, the API returns 400 (Item already exists). Delete the item first (DELETE /api/content-library/items/{item_id}) or use a unique filename (e.g. northwind-runbook-v1-$(date +%s).md).
Expected: Response includes "id", "title", "path", "file_type".
Step 4: Manage Versions and Diff
Duration: 5 minutes
Goal: Replace content in place and compare versions.
4.1 Second version
bash
cat > /tmp/northwind-runbook-v2.md << 'EOF'
# Northwind API Runbook
## Overview
Primary API cluster runs in us-east-1. Secondary warm standby in us-west-2.
## Escalation
Page the on-call via PagerDuty service API-PROD. If unresolved in 15 minutes, escalate to SRE director.
EOF
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
-X PUT -F "file=@/tmp/northwind-runbook-v2.md" \
"$BASE_URL/api/content-library/items/$ITEM_ID/upload" | python3 -m json.toolExpected: "version": 2 (or higher if you repeated).
4.2 Version list
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/items/$ITEM_ID/versions" | python3 -m json.tool4.3 Fetch version bodies
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/items/$ITEM_ID/versions/1" | python3 -m json.tool
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/items/$ITEM_ID/versions/2" | python3 -m json.tool4.4 Unified diff (query params from and to)
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/items/$ITEM_ID/diff?from=1&to=2" | python3 -m json.toolExpected: JSON with diff (unified diff text), from_version, to_version, has_changes.
Step 5: Create Grants (Individual, __all__, Bulk, Templates)
Duration: 8 minutes
Goal: Exercise category and item grants, org-wide category expansion, templates, and bulk grant API.
Assume TARGET_USER_ID is a normal member UUID in your org.
5.1 Single category grant
bash
curl -s "${HDR[@]}" -X POST "$BASE_URL/api/content-library/grants" \
-d "{
\"user_id\": \"$TARGET_USER_ID\",
\"grant_type\": \"category\",
\"grant_value\": \"marketing\"
}" | python3 -m json.tool5.2 Item-level grant
bash
curl -s "${HDR[@]}" -X POST "$BASE_URL/api/content-library/grants" \
-d "{
\"user_id\": \"$TARGET_USER_ID\",
\"grant_type\": \"item\",
\"grant_value\": \"$ITEM_ID\"
}" | python3 -m json.tool5.3 Category __all__ (expands to every known category)
bash
curl -s "${HDR[@]}" -X POST "$BASE_URL/api/content-library/grants" \
-d "{
\"user_id\": \"$TARGET_USER_ID\",
\"grant_type\": \"category\",
\"grant_value\": \"__all__\"
}" | python3 -m json.toolExpected: {"bulk": true, "grants": [...]} listing per-category results.
5.4 List grants and access summary
bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/grants" | python3 -m json.tool
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/grants/summary" | python3 -m json.tool5.5 Grant templates (read-only reference)
bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/grant-templates" | python3 -m json.toolTemplates returned: engineering, leadership, marketing, sales, legal, all — each maps to category lists.
5.6 Bulk grant with template
bash
curl -s "${HDR[@]}" -X POST "$BASE_URL/api/content-library/grants/bulk" \
-d "{
\"user_ids\": [\"$TARGET_USER_ID\"],
\"template_name\": \"engineering\"
}" | python3 -m json.toolExpected: created and skipped counts.
5.7 Optional — access request workflow
As a reader token (same org, without the category), create a request:
bash
curl -s -H "Authorization: Bearer $READER_API_KEY" -H "Content-Type: application/json" \
-X POST "$BASE_URL/api/content-library/access-requests" \
-d "{\"type\": \"category\", \"value\": \"legal\", \"reason\": \"Need MSA templates for deal review\"}" \
| python3 -m json.toolAs admin, list and approve:
bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/access-requests" | python3 -m json.tool
curl -s "${HDR[@]}" -X PATCH \
"$BASE_URL/api/content-library/access-requests/REQUEST_ID_HERE" \
-d '{"status": "approved"}' | python3 -m json.toolUse the real request_id from the list response. Deny with "status": "denied" to test the negative path on a duplicate request.
Step 6: Create a Collection
Duration: 5 minutes
Goal: CRUD-style collection flow with membership.
6.1 Create collection
bash
curl -s "${HDR[@]}" -X POST "$BASE_URL/api/content-library/collections" \
-d '{"name": "Launch Readiness", "description": "Docs for Q1 GA"}' \
| python3 -m json.toolSave id as COLLECTION_ID.
6.2 List collections
bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/collections" | python3 -m json.tool6.3 Add items
bash
curl -s "${HDR[@]}" -X POST \
"$BASE_URL/api/content-library/collections/$COLLECTION_ID/items" \
-d "{\"item_ids\": [\"$ITEM_ID\"]}" | python3 -m json.tool6.4 List collection items
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/collections/$COLLECTION_ID/items" | python3 -m json.tool6.5 Rename collection (PATCH)
bash
curl -s "${HDR[@]}" -X PATCH \
"$BASE_URL/api/content-library/collections/$COLLECTION_ID" \
-d '{"name": "Launch Readiness v2"}' | python3 -m json.tool6.6 Bookmark toggle
bash
curl -s "${HDR[@]}" -X POST \
"$BASE_URL/api/content-library/items/$ITEM_ID/bookmark" | python3 -m json.tool
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/bookmarks" | python3 -m json.tool6.7 Optional cleanup
bash
curl -s "${HDR[@]}" -X DELETE \
"$BASE_URL/api/content-library/collections/$COLLECTION_ID/items/$ITEM_ID" | python3 -m json.tool
curl -s "${HDR[@]}" -X DELETE \
"$BASE_URL/api/content-library/collections/$COLLECTION_ID" | python3 -m json.toolStep 7: Search (Semantic + BM25 + RRF)
Duration: 5 minutes
Goal: Hit hybrid search and interpret scores.
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/search?q=PagerDuty%20escalation" | python3 -m json.toolExpected: Array of { "item": { ... }, "chunk_text": "...", "score": ... }. When embeddings are configured and chunks have vectors, scores reflect BM25-style ranking fused with semantic ranks via RRF; without embeddings, lexical ranking still returns matches from chunk and metadata fallbacks.
Try a looser paraphrase:
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/search?q=who%20do%20we%20page%20for%20API%20outages" \
| python3 -m json.toolRelated items (optional):
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/items/$ITEM_ID/related" | python3 -m json.toolStep 8: Audit Trail and CSV Export
Duration: 5 minutes
Goal: Review structured audit entries and download CSV.
8.1 Paginated audit log
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/audit?limit=50&offset=0" | python3 -m json.toolFilter by action:
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/audit?action=search&limit=20" | python3 -m json.tool8.2 Export CSV (content_library:audit)
bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
"$BASE_URL/api/content-library/audit/export" \
-o /tmp/content-library-audit.csv
head -n 5 /tmp/content-library-audit.csvExpected header row:
Timestamp,User,Action,Document,Document Path,IP,Detail
8.3 Feedback visibility (auditors)
Submit feedback as the reader (same user that can open the item):
bash
curl -s "${HDR[@]}" -X POST \
"$BASE_URL/api/content-library/items/$ITEM_ID/feedback" \
-d '{"type": "helpful", "comment": "Clear escalation path — used in last incident"}' \
| python3 -m json.toolList all feedback for the org:
bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/feedback" | python3 -m json.toolStep 9: Configure External Sources
Duration: 5 minutes
Goal: Register a sync source with source_type and config, then trigger sync.
9.1 List existing sources
bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/sources" | python3 -m json.tool9.2 Create a filesystem source
Use a directory that exists on the backend host (e.g. your repo’s generated-content):
bash
curl -s "${HDR[@]}" -X POST "$BASE_URL/api/content-library/sources" \
-d "{
\"source_type\": \"filesystem\",
\"label\": \"Lab generated-content mirror\",
\"config\": { \"path\": \"/absolute/path/to/generated-content\" }
}" | python3 -m json.toolSave id as SOURCE_ID. Valid source_type values in this release: filesystem, s3, upload. config is stored encrypted server-side.
9.3 Trigger sync
bash
curl -s "${HDR[@]}" -X POST \
"$BASE_URL/api/content-library/sources/$SOURCE_ID/sync" | python3 -m json.toolExpected: For filesystem, status: completed with indexing counts when the path is valid; otherwise an error explaining the missing directory.
9.4 Delete source (optional)
bash
curl -s "${HDR[@]}" -X DELETE \
"$BASE_URL/api/content-library/sources/$SOURCE_ID" | python3 -m json.tool9.5 Platform re-index (optional)
Platform admin only — full scan:
bash
curl -s -H "Authorization: Bearer $PLATFORM_ADMIN_TOKEN" -X POST \
"$BASE_URL/api/content-library/scan" | python3 -m json.toolStep 10: Analytics and Stale Detection
Duration: 5 minutes
Goal: Read aggregate dashboards and stale-content queries.
10.1 Analytics dashboard JSON
bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/analytics" | python3 -m json.toolExpected keys include:
most_viewed— top items by aggregated view_countpopular_categories— category rollupsactive_users_30d— distinct users withviewactions in 30 dayssearch_gaps— recent queries that returned zero resultsleast_viewed— long-tail content candidates for review
10.2 Stale items (default threshold 90 days)
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/stale?days=90" | python3 -m json.toolTighten the window for demos:
bash
curl -s "${HDR[@]}" \
"$BASE_URL/api/content-library/stale?days=30" | python3 -m json.toolExpected: items array with metadata suitable for remediation workflows.
RBAC Quick Reference
| Permission | Typical use |
|---|---|
content_library:read | Browse, search, bookmarks, collections, download, chat attach |
content_library:upload | Role separation for ingest-only users (router may also require manage for some write paths — align roles in your org) |
content_library:manage | Grants, uploads, item flags, sources, access-request decisions, feedback deletion |
content_library:audit | Audit log, CSV export, analytics, stale reports, feedback listing |
Grants (category / item, grant_value or __all__) further restrict which content a reader sees inside the library.
Cleanup (Optional)
Revoke a grant when you know its id:
bash
curl -s "${HDR[@]}" -X DELETE \
"$BASE_URL/api/content-library/grants/GRANT_ID" | python3 -m json.toolDelete the uploaded lab item:
bash
curl -s "${HDR[@]}" -X DELETE \
"$BASE_URL/api/content-library/items/$ITEM_ID" | python3 -m json.toolTroubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| 401 Unauthorized | Missing or invalid Authorization header | Export GHOSTAI_API_KEY |
403 on /items/upload | Lacks content_library:manage | Grant manage to lab user |
403 on /audit | Lacks content_library:audit | Use auditor token |
| 404 on item routes | Wrong ITEM_ID or other org | Re-run upload; check org |
| Empty search | Chunks not indexed yet | Wait; re-sync; check embedding logs |
quota_bytes exceeded | Org over 10 GiB | Delete items or request quota policy change |
For a presenter-led walkthrough of the same capabilities in the UI, see the Content Library Demo Script.