> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ask Milian

> Ask Milian from your API client with explicit approval of additional credits.

Milian can answer questions, analyse permitted workspace data, and recommend next steps through **POST /api/v1/milian/ask** or the **ask\_milian** MCP tool. It does not change workspace resources.

## Approval and credits

Before **every** question, tell the user that Milian uses **additional workspace credits** and ask for explicit approval. Set `confirmed` to `true` only after that approval. Connecting a client or granting access does not approve future paid questions.

Usage is charged to the active workspace at the **same rates as Milian in the dashboard**. Available credits are checked before generation. The response reports the credits actually charged; completed work may still be charged if a later step fails. Each follow-up or retry is a new paid question: do not retry automatically.

## Access

Use a workspace API key or OAuth token with `milian:write`. Data access also requires the relevant read scopes, such as `calls:read`. For OAuth, select **Milian** and the data groups you want it to analyse. Milian is optional and is not included in the default seven groups or the public assistant-history profile. Viewer and billing roles cannot start paid questions.

Questions are standalone. Include the context Milian needs; these questions are not added to dashboard chat history.

## Request

```bash theme={null}
curl -X POST https://app.famulor.io/api/v1/milian/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Analyse my recent calls and suggest improvements.","confirmed":true,"locale":"en"}'
```

Only run this example after the user has approved the additional credits. On your own branded domain, use that domain in place of `app.famulor.io`.

## Response

```json theme={null}
{"data":{"id":"00000000-0000-4000-8000-000000000001","status":"completed","answer":"Your analysis…","credits":2.35,"billing_complete":true}}
```

The credit amount above is illustrative, not a fixed price. Check `status` and `billing_complete` before treating the request as complete. Insufficient credits before generation return HTTP 402. A missing approval returns HTTP 400. Unauthorized scopes or roles return HTTP 403.

See [MCP tools and scopes](/mcp/tools-and-scopes) for connection setup.

## Live voice chat (Beta)

Create the same connection from the CLI with `famulor create-milian-voice-session --approve-credit-usage --context '{"locale":"en"}'`. Pass its URL and protocols to your voice-capable client. The CLI creates the session; the connected client supplies audio, page context or selected screen images using the protocol below.

Use **POST /api/v1/milian/voice-sessions** or **create\_milian\_voice\_session** to start a voice session. Enable workspace **Beta Features** and use a user credential with `milian:write` and a writable workspace role. Available tools retain the same credential scopes and OAuth tool groups. Each session starts a new conversation; private dashboard memories and existing conversations are not loaded through this API.

Tell the user that voice and shared-screen analysis consume **additional workspace credits**, then obtain explicit approval for this session before sending `{"approve_credit_usage":true,"context":{"locale":"en"}}`. A new session or retry requires new approval. Approval of voice credits does not authorize purchases, publishing, destructive changes or contacting others.

Connect within `expires_in` seconds using `new WebSocket(data.url, data.protocols)`. The connection is single-use. Treat the returned protocols as temporary credentials. Browser clients connect from the same origin as the returned URL; native clients can connect without a browser Origin header.

After `{"type":"ready"}`, send mono 16 kHz PCM16 little-endian audio as `{"type":"audio","audio":"BASE64"}`. Receive `{"type":"audio","audio":"BASE64"}` in mono 24 kHz PCM16. Clear queued playback on `{"type":"interrupt"}`. Optional text input is `{"type":"text","text":"Help me with this setting"}`. Send `{"type":"ping"}` every 10 seconds.

When muting or pausing microphone capture, send `{"type":"audio-pause"}` once to finish the current audio segment. Text input remains available; resume by sending audio chunks again.

Screen capture requires explicit user selection. Send `{"type":"screen","image":"data:image/jpeg;base64,…"}` at most once every 12 seconds, under 240,000 characters. Send the first image about a second after approval, so the browser's share picker is not in it. Before Milian inspects the screen, the connection emits `{"type":"screen-request"}`: answer right away with a current image. Without an answer within two seconds, Milian uses the latest image. The image is analyzed separately when the conversation needs screen context; each refresh does not start another user turn. Send `{"type":"screen-stop"}` and stop capturing when sharing ends to discard the current image; raw audio and screenshots are not saved as chat attachments.

For optional application page context, a client can send `{"type":"page-context","text":"Visible page text and controls"}` after `ready`, with at most 12,000 characters. Tell the user what is shared, offer a pause control, and exclude secrets, field values and hidden content. Refresh after navigation or visible changes and at least every ten seconds while enabled; context expires after thirty seconds. Send `{"type":"page-context-stop"}` when paused, hidden or leaving the workspace. These updates remain passive until Milian needs to inspect the page. After browser screen approval, send `{"type":"screen-start"}` to discard page context before the first image arrives. Page updates are ignored during screen sharing. After `screen-stop`, send a fresh page context to resume; old page text is never restored automatically.

The connection emits `transcript` updates, `message` records, `screen-status`, `screen-request`, `usage` with charged credits, and `error` or `ended`. Display the charged credits. Send `{"type":"stop"}` to finish, stop all media tracks, and briefly wait for final usage before closing. Disconnection and the session limit also end processing. The plan limit is reported as `max_seconds`; the connection may end slightly earlier to save final usage. Only one voice session can be active per workspace.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.