curl --request POST \
--url https://akapulu.com/api/conversations/{conversation_session_id}/system-messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"content": "Background research is complete. The patient's last A1C was 7.2. Use this if they ask about lab results.",
"run_llm": false
}
EOF{
"conversation_session_id": "7f1e7f76-b38d-4d03-b8f8-2570ce8d4e6d",
"run_llm": false
}{
"error": "content is required",
"error_code": "VALIDATION"
}{
"error": "Invalid API key",
"error_code": "AUTH_INVALID"
}{
"error": "ConversationSession not found",
"error_code": "SESSION_NOT_FOUND"
}{
"error": "Failed to enqueue system message",
"error_code": "SERVICE_UNAVAILABLE"
}During a conversation
Post a System Message
Append a system message to a live conversation’s LLM context. The message is not spoken and is not a user turn. Call this from your server with an API key. The session id must belong to the API key owner (live conversation or Testing Mode).
POST
/
conversations
/
{conversation_session_id}
/
system-messages
curl --request POST \
--url https://akapulu.com/api/conversations/{conversation_session_id}/system-messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"content": "Background research is complete. The patient's last A1C was 7.2. Use this if they ask about lab results.",
"run_llm": false
}
EOF{
"conversation_session_id": "7f1e7f76-b38d-4d03-b8f8-2570ce8d4e6d",
"run_llm": false
}{
"error": "content is required",
"error_code": "VALIDATION"
}{
"error": "Invalid API key",
"error_code": "AUTH_INVALID"
}{
"error": "ConversationSession not found",
"error_code": "SESSION_NOT_FOUND"
}{
"error": "Failed to enqueue system message",
"error_code": "SERVICE_UNAVAILABLE"
}Append a system message to a live conversation’s LLM context while the call is in progress.
The posted
It is not spoken, and it is not a user turn. Use this from your server with an API key, not from browser code.
For the workflow, see Updating Conversation Context.
On failure the body includes
content is added as exactly one message:
{ "role": "system", "content": "<your content>" }
error and error_code. See Error responses.
Required headers:
Authorization: Bearer <YOUR_AKAPULU_API_KEY>Content-Type: application/json
content: non-empty string, at most 16,000 characters
run_llm: boolean, defaultfalsefalse: append the system message only. The assistant sees it on the next LLM run (typically the next user turn).true: append the system message and immediately run the LLM so the assistant can reply.
curl -X POST "https://akapulu.com/api/conversations/7f1e7f76-b38d-4d03-b8f8-2570ce8d4e6d/system-messages/" \
-H "Authorization: Bearer <YOUR_AKAPULU_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"content": "Chart review is complete. Last A1C was 7.2. Share that if the patient asks.",
"run_llm": false
}'
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Conversation session ID from connect, or X-Akapulu-Conversation-Session-Id on an HTTP tool POST.
Body
application/json
Text appended to the live LLM context as a system message. Not spoken and not treated as a user turn.
Required string length:
1 - 16000If false (default), only append the system message. If true, also trigger an assistant reply that can see the new context.