Skip to content

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, sources
    • content_library:audit — audit, analytics, stale, feedback list
  • [ ] curl, python3 -m json.tool, and jq installed (brew install jq on 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.tool

Expected: "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.tool

Expected: 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.tool

2.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.tool

2.3 List items (optional filters) ​

bash
curl -s "${HDR[@]}" \
  "$BASE_URL/api/content-library/items?category=engineering" | python3 -m json.tool

With text filter:

bash
curl -s "${HDR[@]}" \
  "$BASE_URL/api/content-library/items?search=runbook" | python3 -m json.tool

2.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.tool

Expected: 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.
EOF

Upload (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.tool

Expected: "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.tool

4.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.tool

4.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.tool

Expected: 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.tool

5.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.tool

5.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.tool

Expected: {"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.tool

5.5 Grant templates (read-only reference) ​

bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/grant-templates" | python3 -m json.tool

Templates 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.tool

Expected: 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.tool

As 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.tool

Use 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.tool

Save id as COLLECTION_ID.

6.2 List collections ​

bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/collections" | python3 -m json.tool

6.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.tool

6.4 List collection items ​

bash
curl -s "${HDR[@]}" \
  "$BASE_URL/api/content-library/collections/$COLLECTION_ID/items" | python3 -m json.tool

6.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.tool

6.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.tool

6.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.tool

Step 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.tool

Expected: 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.tool

Related items (optional):

bash
curl -s "${HDR[@]}" \
  "$BASE_URL/api/content-library/items/$ITEM_ID/related" | python3 -m json.tool

Step 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.tool

Filter by action:

bash
curl -s "${HDR[@]}" \
  "$BASE_URL/api/content-library/audit?action=search&limit=20" | python3 -m json.tool

8.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.csv

Expected 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.tool

List all feedback for the org:

bash
curl -s "${HDR[@]}" "$BASE_URL/api/content-library/feedback" | python3 -m json.tool

Step 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.tool

9.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.tool

Save 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.tool

Expected: 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.tool

9.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.tool

Step 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.tool

Expected keys include:

  • most_viewed — top items by aggregated view_count
  • popular_categories — category rollups
  • active_users_30d — distinct users with view actions in 30 days
  • search_gaps — recent queries that returned zero results
  • least_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.tool

Tighten the window for demos:

bash
curl -s "${HDR[@]}" \
  "$BASE_URL/api/content-library/stale?days=30" | python3 -m json.tool

Expected: items array with metadata suitable for remediation workflows.


RBAC Quick Reference ​

PermissionTypical use
content_library:readBrowse, search, bookmarks, collections, download, chat attach
content_library:uploadRole separation for ingest-only users (router may also require manage for some write paths — align roles in your org)
content_library:manageGrants, uploads, item flags, sources, access-request decisions, feedback deletion
content_library:auditAudit 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.tool

Delete the uploaded lab item:

bash
curl -s "${HDR[@]}" -X DELETE \
  "$BASE_URL/api/content-library/items/$ITEM_ID" | python3 -m json.tool

Troubleshooting ​

SymptomLikely causeFix
401 UnauthorizedMissing or invalid Authorization headerExport GHOSTAI_API_KEY
403 on /items/uploadLacks content_library:manageGrant manage to lab user
403 on /auditLacks content_library:auditUse auditor token
404 on item routesWrong ITEM_ID or other orgRe-run upload; check org
Empty searchChunks not indexed yetWait; re-sync; check embedding logs
quota_bytes exceededOrg over 10 GiBDelete items or request quota policy change

For a presenter-led walkthrough of the same capabilities in the UI, see the Content Library Demo Script.

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