Appearance
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 asBearerauth) jqinstalled 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)
| Method | Path | Notes |
|---|---|---|
POST | /api/assistants | Create (AssistantCreate), 201 |
GET | /api/assistants | List; 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}/duplicate | Clone; 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
| HTTP | Meaning |
|---|---|
403 on /api/assistants routes | Feature assistants disabled, or not the creator for mutating calls |
404 on GET / PUT / DELETE | Unknown assistant_id |
422 | Body violates Pydantic limits (name length, max_tokens range, etc.) |
| Chat ignores assistant | Missing or invalid assistant_id, or user cannot access assistant |
| Upload fails | Auth, virus scan settings, or size/type limits — see GET /api/files/info/limits |
What you learned
- Creating and listing assistants with exact
/api/assistantspaths fromassistants.py - Org sharing via
is_sharedandGET /api/assistants?shared_only=true - Cloning with
POST /api/assistants/{id}/duplicate - Partial updates via
PUT - Wiring
knowledge_file_idsto realPOST /api/files/uploadIDs - Passing
assistant_idintoPOST /api/chat(and optionallyPOST /api/chat/compare) - Deleting with
DELETE /api/assistants/{id}(204)
You now have a repeatable, scriptable checklist aligned with the production router implementation.