Skip to content

Custom Assistants — Full Lab ​

This lab exercises the Custom Assistants API mounted at /api/assistants (router prefix in securechat/backend/app/routers/assistants.py). Every step uses curl and assumes:

  • Base URL: http://localhost:8000 (change if yours differs)
  • JWT in TOKEN (same value the UI stores as Bearer auth)
  • jq installed for pretty-printing (optional)
bash
export BASE_URL="http://localhost:8000"
export TOKEN="paste_jwt_here"

All assistant endpoints require the assistants feature flag for the authenticated principal.


Reference: Endpoints (from assistants.py) ​

MethodPathNotes
POST/api/assistantsCreate (AssistantCreate), 201
GET/api/assistantsList; query shared_only=true for org-shared only
GET/api/assistants/{assistant_id}Get one; 403 if no access
PUT/api/assistants/{assistant_id}Update (AssistantUpdate); creator only
DELETE/api/assistants/{assistant_id}Delete; creator only, 204
POST/api/assistants/{assistant_id}/duplicateClone; 201, copy owned by caller

Request bodies use JSON. Field limits match Pydantic models in the same file: name 1–200, description ≤2000, instructions ≤50000, starter_message ≤10000, optional max_tokens 1–65536, optional max_tool_rounds 1–15.


Step 1 — Create an assistant (POST /api/assistants) ​

Create a private assistant with instructions, starter text, default models, and optional caps. Start without knowledge files; you will attach IDs in Step 7.

bash
curl -sS -X POST "${BASE_URL}/api/assistants" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lab: Policy Assistant",
    "description": "Hands-on assistant for curl lab; answers from attached policy text only.",
    "instructions": "You are a compliance helper. Use only the attached documents. If the answer is not in the files, say you do not have enough context.",
    "knowledge_file_ids": [],
    "is_shared": false,
    "icon": "📋",
    "default_models": ["gpt-4o-mini", "gpt-4o"],
    "starter_message": "What retention rules apply to customer emails?",
    "max_tokens": 2048,
    "max_tool_rounds": 8
  }' | tee /tmp/assistant_create.json | jq .

Capture the new id:

bash
export ASSISTANT_ID="$(jq -r .id /tmp/assistant_create.json)"
echo "ASSISTANT_ID=${ASSISTANT_ID}"

Success criteria: HTTP 201, JSON includes id, created_by, organization_id (may be null), is_shared: false, and your default_models / max_tokens / max_tool_rounds.


Step 2 — List assistants (GET /api/assistants) ​

2a — Everything you can access (own + org shared) ​

bash
curl -sS "${BASE_URL}/api/assistants" \
  -H "Authorization: Bearer ${TOKEN}" | jq .

2b — Organization shared catalog only ​

bash
curl -sS "${BASE_URL}/api/assistants?shared_only=true" \
  -H "Authorization: Bearer ${TOKEN}" | jq .

When the user has no organization_id, the implementation still returns assistants visible to that user (typically personal assistants only).

2c — Fetch one assistant ​

bash
curl -sS "${BASE_URL}/api/assistants/${ASSISTANT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" | jq .

Success criteria: GET "" returns an array containing your assistant; GET /{id} returns the full AssistantResponse object.


Step 3 — Use an assistant in chat (POST /api/chat) ​

Chat is mounted under /api in main.py, so the path is POST /api/chat. Send a message plus assistant_id. The backend resolves the assistant, merges knowledge_file_ids into attachments, and sets custom_system_prompt from instructions when you omit custom_system_prompt.

Use a model your deployment allows:

bash
curl -sS -X POST "${BASE_URL}/api/chat" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"In one sentence, what are you allowed to use as sources?\",
    \"model\": \"gpt-4o-mini\",
    \"assistant_id\": \"${ASSISTANT_ID}\",
    \"save_to_history\": false
  }" | jq .

Success criteria: HTTP 200, response reflects the assistant instructions (e.g. only attached documents). With no knowledge files yet, the model should admit limited context—consistent with your instructions.

Override check: repeat with an explicit custom_system_prompt in the body; that value should take precedence over assistant instructions for that request.


Step 4 — Share with the organization (PUT /api/assistants/{assistant_id}) ​

Only the creator may update. Toggle sharing:

bash
curl -sS -X PUT "${BASE_URL}/api/assistants/${ASSISTANT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"is_shared": true}' | jq .

Verify with another user token from the same organization:

bash
export PEER_TOKEN="peer_jwt_same_org"
curl -sS "${BASE_URL}/api/assistants?shared_only=true" \
  -H "Authorization: Bearer ${PEER_TOKEN}" | jq .

Success criteria: Peer sees the assistant in shared_only listing; GET /api/assistants/{id} works for the peer; PUT / DELETE from the peer returns 403 with “Only the creator…”.


Step 5 — Duplicate an assistant (POST /api/assistants/{assistant_id}/duplicate) ​

bash
curl -sS -X POST "${BASE_URL}/api/assistants/${ASSISTANT_ID}/duplicate" \
  -H "Authorization: Bearer ${TOKEN}" | tee /tmp/assistant_dup.json | jq .
bash
export ASSISTANT_COPY_ID="$(jq -r .id /tmp/assistant_dup.json)"
echo "ASSISTANT_COPY_ID=${ASSISTANT_COPY_ID}"

Success criteria: HTTP 201, name ends with (Copy), created_by matches the caller, is_shared is false, fields copied from the source.

The new row is always owned by the caller. Use an assistant_id from your own listings (or from org-shared listings you trust) so you are cloning the configuration you intend.


Step 6 — Update instructions (PUT /api/assistants/{assistant_id}) ​

Point the update at the copy so you do not disturb the shared original:

bash
curl -sS -X PUT "${BASE_URL}/api/assistants/${ASSISTANT_COPY_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are a sales-focused helper. Keep answers under 80 words. Prefer bullet lists.",
    "starter_message": "Give me three discovery questions for a CISO."
  }' | jq .

Success criteria: updated_at changes; instructions and starter_message match the payload; omitted fields remain unchanged.


Step 7 — Manage knowledge files ​

knowledge_file_ids must be file attachment IDs from the files API.

7a — Upload a text file (POST /api/files/upload) ​

bash
printf '%s\n' "Retention: customer emails 7 years. Support tickets 3 years." > /tmp/lab_retention.txt

curl -sS -X POST "${BASE_URL}/api/files/upload" \
  -H "Authorization: Bearer ${TOKEN}" \
  -F "file=@/tmp/lab_retention.txt;type=text/plain" | tee /tmp/file_upload.json | jq .
bash
export FILE_ID="$(jq -r .attachment.id /tmp/file_upload.json)"
echo "FILE_ID=${FILE_ID}"

7b — Attach to the assistant (PUT /api/assistants/{assistant_id}) ​

bash
curl -sS -X PUT "${BASE_URL}/api/assistants/${ASSISTANT_COPY_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"knowledge_file_ids\": [\"${FILE_ID}\"]}" | jq .

7c — Chat again with assistant_id ​

bash
curl -sS -X POST "${BASE_URL}/api/chat" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"How long do we keep customer emails?\",
    \"model\": \"gpt-4o-mini\",
    \"assistant_id\": \"${ASSISTANT_COPY_ID}\",
    \"save_to_history\": false
  }" | jq .

7d — Remove knowledge files (empty list) ​

bash
curl -sS -X PUT "${BASE_URL}/api/assistants/${ASSISTANT_COPY_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_file_ids": []}' | jq .

Success criteria: With files attached, the answer cites the retention policy; after clearing knowledge_file_ids, the assistant should no longer ground in that upload (subject to model behavior).

Optional: GET ${BASE_URL}/api/files/${FILE_ID}/metadata confirms the attachment exists.


Step 8 — Delete assistants (DELETE /api/assistants/{assistant_id}) ​

Delete the copy first, then the original (only the creator of each may delete).

bash
curl -sS -o /dev/null -w "%{http_code}\n" -X DELETE \
  "${BASE_URL}/api/assistants/${ASSISTANT_COPY_ID}" \
  -H "Authorization: Bearer ${TOKEN}"
bash
curl -sS -o /dev/null -w "%{http_code}\n" -X DELETE \
  "${BASE_URL}/api/assistants/${ASSISTANT_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

Success criteria: HTTP 204 for each delete; subsequent GET returns 404.


Bonus — Compare endpoint with an assistant (POST /api/chat/compare) ​

CompareRequest accepts assistant_id, models (1–4 entries), optional max_tokens, optional custom_system_prompt. Assistant resolution merges knowledge IDs and instructions like single chat.

bash
curl -sS -N -X POST "${BASE_URL}/api/chat/compare" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d "{
    \"message\": \"One sentence: what sources may you use?\",
    \"models\": [\"gpt-4o-mini\", \"gpt-4o\"],
    \"assistant_id\": \"${ASSISTANT_ID}\",
    \"max_tokens\": 256
  }"

Run this before Step 8 while ASSISTANT_ID still exists. Expect an SSE stream with per-model events (compare_start, compare_chunk, etc.).


Troubleshooting ​

HTTPMeaning
403 on /api/assistants routesFeature assistants disabled, or not the creator for mutating calls
404 on GET / PUT / DELETEUnknown assistant_id
422Body violates Pydantic limits (name length, max_tokens range, etc.)
Chat ignores assistantMissing or invalid assistant_id, or user cannot access assistant
Upload failsAuth, virus scan settings, or size/type limits — see GET /api/files/info/limits

What you learned ​

  • Creating and listing assistants with exact /api/assistants paths from assistants.py
  • Org sharing via is_shared and GET /api/assistants?shared_only=true
  • Cloning with POST /api/assistants/{id}/duplicate
  • Partial updates via PUT
  • Wiring knowledge_file_ids to real POST /api/files/upload IDs
  • Passing assistant_id into POST /api/chat (and optionally POST /api/chat/compare)
  • Deleting with DELETE /api/assistants/{id} (204)

You now have a repeatable, scriptable checklist aligned with the production router implementation.

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