> ## Documentation Index > Fetch the complete documentation index at: https://docs.akapulu.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Pick a path before writing code. > Share a live avatar call with no code: use a hosted link (a public URL). No SDK and no API key in the customer's app. > Embed a live conversation in an app: use the Web SDK. @akapulu/server 1.0.3+ on the backend, @akapulu/react or @akapulu/react-ui in the browser. Do not call POST /conversations/connect or updates from frontend code with the API key. Do not reimplement those two calls with fetch. > Scripted talking-avatar video (offline, not a live call): use the clip and take REST API, or the Python clip example. No Web SDK. > Create and manage scenarios, hosted links, HTTP endpoints, knowledge bases and documents, and clips and takes with the REST API. Keep AKAPULU_API_KEY on the server for every REST call. Never put the key in frontend or Vite code. > If embedding: the browser calls YOUR connect and updates routes. Authenticate users on those routes before starting a billed call. Demo examples skip that check. User auth is config.headers (object or a function called when the request is sent). connectBody is JSON payload, not auth. > Do not install Daily or Pipecat yourself; they come with @akapulu/react. Add @daily-co/daily-react only if your own files import DailyVideo. > Conversation API errors include error_code. Branch on that field, not the English error string. # 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). Append a **system** message to a live conversation's LLM context while the call is in progress. The posted `content` is added as exactly one message: ```json theme={null} { "role": "system", "content": "" } ``` 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](/guides/conversations/updating-conversation-context). On failure the body includes `error` and `error_code`. See [Error responses](/api-reference/introduction#error-responses). Required headers: * `Authorization: Bearer ` * `Content-Type: application/json` Required request fields: * `content`: non-empty string, at most 16,000 characters Optional request fields: * `run_llm`: boolean, default `false` * `false`: 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. The session id in the path must be owned by the API key. Live conversations from [connect](/api-reference/conversations/connect) and [Testing Mode](/guides/scenarios/llm-test-mode) sessions both work. Example request: ```bash theme={null} curl -X POST "https://akapulu.com/api/conversations/7f1e7f76-b38d-4d03-b8f8-2570ce8d4e6d/system-messages/" \ -H "Authorization: Bearer " \ -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 }' ``` ## OpenAPI ````yaml openapi/akapulu.json POST /conversations/{conversation_session_id}/system-messages openapi: 3.1.0 info: title: Akapulu Labs API version: 1.0.0 description: Public Akapulu Labs API reference. servers: - url: https://akapulu.com/api security: - bearerAuth: [] paths: /conversations/{conversation_session_id}/system-messages: post: summary: Post a system message description: >- 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). parameters: - name: conversation_session_id in: path required: true description: >- Conversation session ID from connect, or `X-Akapulu-Conversation-Session-Id` on an HTTP tool POST. schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SystemMessageRequest' examples: inject_only: summary: Append context without speaking value: content: >- Background research is complete. The patient's last A1C was 7.2. Use this if they ask about lab results. run_llm: false inject_and_speak: summary: Append context and have the assistant reply now value: content: >- The chart review is done. Summarize the A1C result for the patient in one short sentence. run_llm: true responses: '200': description: System message queued for the live session content: application/json: schema: $ref: '#/components/schemas/SystemMessageResponse' examples: success: value: conversation_session_id: 7f1e7f76-b38d-4d03-b8f8-2570ce8d4e6d run_llm: false '400': description: Invalid request payload content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: missing_content: value: error: content is required error_code: VALIDATION '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: invalid_key: value: error: Invalid API key error_code: AUTH_INVALID '404': description: Conversation session not found or not owned by this API key content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: missing_session: value: error: ConversationSession not found error_code: SESSION_NOT_FOUND '503': description: Could not enqueue the system message content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: queue_unavailable: value: error: Failed to enqueue system message error_code: SERVICE_UNAVAILABLE components: schemas: SystemMessageRequest: type: object required: - content properties: content: type: string minLength: 1 maxLength: 16000 description: >- Text appended to the live LLM context as a system message. Not spoken and not treated as a user turn. run_llm: type: boolean default: false description: >- If false (default), only append the system message. If true, also trigger an assistant reply that can see the new context. SystemMessageResponse: type: object required: - conversation_session_id - run_llm properties: conversation_session_id: type: string format: uuid description: Session that received the system message. run_llm: type: boolean description: Echo of the request `run_llm` value. ApiError: type: object required: - error properties: error: type: string description: Human-readable error message. error_code: type: string description: >- Stable machine code for this error. Switch on this field, not the HTTP status or the `error` sentence. enum: - AUTH_MISSING - AUTH_INVALID - AUTH_DENIED - VALIDATION - SCENARIO_NOT_FOUND - AVATAR_NOT_FOUND - SESSION_NOT_FOUND - NOT_FOUND - QUOTA_EXCEEDED - CONCURRENCY_LIMIT - RECORDING_NOT_STARTED - RECORDING_UNAVAILABLE - RECORDING_PROCESSING - SERVICE_UNAVAILABLE - INTERNAL securitySchemes: bearerAuth: type: http scheme: bearer ````