---
title: "Manage Assistant"
method: POST
path: "/api/facade/manage_assistant"
tags: ["facade"]
---

# Manage Assistant

`POST /api/facade/manage_assistant`

## Request

- Base URL: `https://api.vruum.ai`
- URL: `https://api.vruum.ai/api/facade/manage_assistant`
- Auth: `HTTPBearer` (a scheme the document does not define)

Chat with Vruum: the same chat as the floating panel in the app.

- start_conversation: no id; payload={request_id (UUID), message,
  context?, browser_context?}. Starts a new chat and waits up to 50 s for the answer.
  context={kind: person|account|deal|objective, id} names a record to
  focus on; context={kind: people|accounts|deals, params} names a table
  and its filters (a saved view's keys). Returns chat_id, the turn
  (state completed, failed, stopped, interrupted, running or
  awaiting_approval), the question, the answer, changes and cards.
- append_message: id=chat UUID; payload={request_id, message, context?, browser_context?}.
  Sends the next message in that chat and waits the same way. One message
  runs at a time per chat.
- undo: id=a change's item UUID from changes or inspect_assistant read; no
  payload. Runs the change's exact inverse; refused when the record was
  edited since.
- decide_card: id=a pending card's item UUID from cards; payload=
  {decision: approved|declined}. Call only with the user's own decision on
  that exact card. approved runs the card's exact call once under your
  credentials; declined never runs it. Waits up to 50 s for the turn to
  continue; claimed=false means the card was already decided or expired.
- rate: id=an answer's message UUID; payload={rating: 1|-1|0, reasons?,
  comment?}. reasons: wrong_facts, did_not_do_it, wrong_record, too_slow,
  hard_to_follow, other. 0 clears the rating.
- job_start: no id; payload={request_id, request_key, request: {text,
  completion_condition, source_scope?, source_domains?}, guidance?}. Hands a request too
  large for one chat turn off to Vruum (shown to users as a Request in
  Agent work): it reads with your access, writes its analysis as the
  result and prepares drafts that keep their own approval. The whole
  workspace sees it; the chat stays private. The same request_key returns
  the same request. For public multi-page research, include source_domains
  (named public domains). This uses isolated browser research with search,
  fetch and rendered pages, retained sources and the same Request controls.
- job_control: id=Delegation UUID; payload={command: pause|resume|cancel|
  steer|takeover, request_id, expected_revision, guidance (steer only)}.
  Its grantor controls a request; a workspace admin pauses, stops or takes
  it over after the grantor loses access. Read it with
  inspect_assistant action=job.

browser_context={binding_id, snapshot_id} is an optional immutable Radar
page reference, separate from CRM context. Keep it unchanged on retries.
Read saved evidence with inspect_assistant action=browser_source.

Vruum reads your records and applies reversible record changes at once
(notes, tasks, roles, contact choices, deal stages), each listed in
changes with Undo. Other actions (archive, objective members, launch, a
one-off send, paid lookups) become a card: the turn returns
state=awaiting_approval and nothing runs until decide_card. It never
approves drafts. A turn still running after 50 s returns state=running:
read the chat later with inspect_assistant. Keep the same request_id when you retry
after an uncertain response; the server runs each request once. Call only
after the user asks for the message to be sent.

## Request body

- WriterRequest: Uniform request body for every facade writer.
  - `action` string, required: The operation to perform — see the tool description for the action vocabulary and each action's id/payload semantics.
  - `id` union: Target entity id, or an ARRAY of ids to apply the same action+payload to each (max 100; see the tool description for which entity the id names per action).
    - string
    - string[]
  - `payload` object, nullable: Action-specific fields, validated by the underlying route's own schema (a bad field 422s with that route's precise errors). See the tool description per action.
  - `items` object[], nullable: For create-like actions only: an array of per-item payloads processed in order with per-item results (max 100). Mutually exclusive with `id` and `payload`.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/vruum/apis/vruum-public-api.md) · [All operations](https://skmtc.dev/vruum/apis/vruum-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vruum/apis/vruum-public-api/revisions/b8ada111c30a?raw)