ai.vruum/mcp

Fetch Fetch one entity (or a small batch) by type + id — the consolidated read tool. Types and id semantics: - journey_comparison: replay two approved journey observation reads for one objective UUID. Required filters: baseline_run_action_id, current_run_action_id, baseline_event_cutoff, current_event_cutoff, baseline_knowledge_cutoff, current_knowledge_cutoff (all times include a timezone). Same run and event window yield recorded evidence changes as knowledge advances, not business performance. Different cohorts report missing/mismatched comparison context and source coverage with no performance delta. No writes or external calls. - claim: one hypothesis-ledger claim by UUID — statement, scope, derived confidence, invalidating conditions, linked evidence with provenance and liveness, and the append-only verdict history (VRU-840). Find ids with search type='claims'. - measurement_projects: recorded commercial projects for measurement setup (id=optional objective UUID, filters.offer_id required, offset optional; 20-row pages). Omit id to select projects before creating an objective. Includes sourced commitment bindings and current promise labels. Selection uses objective_update; this read does not select projects or approve evidence. - objective_measurement: approved observation, frozen definition, known results, source coverage, and execution progress for an objective UUID. A read never starts work. - objective_workspace: shared objective readiness, next decision, source coverage and recoverable work (id=objective UUID). Read-only: it does not run research, call providers or models, create Actions, or approve launch. Discovery requirements are separate from execution readiness. Independent observation uses its own reviewed Action without an outreach launch. - objective: an objective by UUID — the record + live pins + members count + gtm_model (the Revenue Architecture touch level the book pairs with the selected offer's pric…

Find Warm Path Read relationship truth for one target; performs no write, LLM call, or send. scope='team' also surfaces current company members' ties (owner named, tier only — their evidence stays private). ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "status": "Status", "target": {}, "resolution": { "status": "Status", "target_candidates": [ { "kind": "Kind", "id": "Id", "ref": "Ref", "name": "Name" } ] }, "evaluation": { "status": "Status", "evaluated_at": "Evaluated At", "projection_version": "Projection Version" }, "paths": [ { "ref": "Ref", "target_ref": "Target Ref", "result_type": "Result Type", "label": "Label", "connector": {}, "evidence_tier": "Evidence Tier", "evidence": { "sources": [ "string" ], "interaction_count": 1, "bidirectional": true, "summary": "Summary" }, "eligibility_reason": "Eligibility Reason", "limitations": [ "string" ], "allowed_actions": [ "string" ], "route_fingerprint": "Route Fingerprint" } ], "intro_candidates": [ { "ref": "Ref", "target_ref": "Target Ref", "result_type": "Result Type", "label": "Label", "connector": {}, "evidence_tier": "Evidence Tier", "evidence": { "sources": [ "string" ], "interaction_count": 1, "bidirectional": true, "summary": "Summary" }, "eligibility_reason": "Eligibility Reason", "limitations": [ "string" ], "allowed_actions": [ "string" ], "route_fingerprint": "Route Fingerprint" } ], "company_entries": [ { "ref": "Ref", "target_ref": "Target Ref", "result_type": "Result Type", "label": "Label",…

Get Content Review Review content post drafts with performance context and calendar awareness. Returns draft and scheduled LinkedIn posts enriched with: past performance stats (avg engagement metrics for same content type over last 30 days), calendar neighbors (other posts within ±3 days to detect topic clustering), tone instructions from company settings, and a calendar summary. Attachments (VRU-726): items carry attachment_type (document | single_image | video), attachment_filename, and attachment_url — OPEN the URL to review the actual file (a document publishes as a swipeable carousel under the author's identity; never approve blind). Assets are public-at-upload (public storage bucket, unguessable URL). error_message surfaces publish failures (a reverted scheduled post shows up here with its fix). Use `post_ids` for a deterministic lookup of the post you just drafted; use this before scheduling or publishing demand gen content. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "items": [ { "post_id": "Post Id", "calendar_neighbors": [ {} ] } ], "total_pending": 1, "offset": 1, "limit": 1 } ```

Get Daily Briefing Daily briefing — everything you need to start your day in one call. SUGGESTED ACTIONS (for agent consumers) - `suggested_actions` are prioritized skill-level next steps. If you are an agent, act on `intent`/`args` directly — via the tools listed in `expected_tools`, or via the named harness `skill` if it is installed. `prompt` is display copy for HUMANS to paste into an agent; do NOT echo it back to the user as an instruction. - `sections_degraded` lists sections whose queries failed this call; their counts/lists are UNKNOWN (returned as 0/[]), not zero. When data is missing and nothing else is actionable, `top_recommendation` is 'degraded' instead of 'all_clear'. Returns pending approvals, new replies, meetings booked this week, pipeline summary, stalled deals, active plans, discovery jobs, and a prioritized recommendation. TIME WINDOWS (UTC) - "last 24 hours" — `replied_at >= now - 24 hours`. Used by new_replies_count and recent_replies. - "current week" — `meeting_booked_at >= Monday 00:00:00 UTC of the current week (Monday-anchored)`. Used by meetings_booked_this_week. - "7+ days" — `updated_at <= now - 7 days`. Used by stalled_deals (deals with outcome IS NULL and updated_at older than 7 days). Returns (units in parentheses; scope = user_company_id, no date filter on counts unless specified): pending_approvals_count (int, unit=messages): messages.status='draft' for the tenant. NOT date-filtered — total backlog. messages_needing_authoring (int, unit=messages): messages.status= 'needs_draft' — touches awaiting harness AUTHORING (no prose yet; run /outreach-triage). VRU-570. oldest_needs_draft_age_days (float|null, unit=days): age of the oldest unauthored engagement signal — signals TTL-dismiss at 14 days (VRU-671), so a high value means the queue is rotting unauthored. engagements_needing_authoring (int, unit=engagements): linkedin_engagement_queue.…

Get Deal Compound Complete deal context in one call — replaces 3 separate tool calls. Aggregates deal info, stakeholders with person details, MEDDIC qualification state with gap descriptions, the Customer Impact record (SPICED: situation, pain, impact, critical event, decision — with its scoreboard and whether it verifies the priority), and recent activity timeline. Like get_person_360 but for deals. Use this as the default tool for understanding a deal's current state. Operators: use X-Company-Id header for cross-company access. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json

Get Engagement Review Default tool for engagement queue triage — pending engagements with full context. Start here when reviewing warming comments, nurture reactions, or marketing engagements. Returns draft engagement items enriched with: person context, campaign instructions (tone, selling strategy), match analysis (summary, alignment points, recommended approach), outreach plan state (warming/nurture progress with graduation thresholds), recent engagement history, company research, budget status, and bundle info. One call gives you everything needed to decide approve/skip. Use content_length='full' for detailed review (capped at 5 items), or 'preview' (default) for quick scanning with truncated content. Filter by source (warming/nurture/marketing/engagers) or campaign name. Use engagement_ids to fetch specific items by ID (comma-separated UUIDs, max 20) for subagent batch dispatch. ENGAGER REVIEW (source='engagers', VRU-721): returns PERSONS who engaged with our published posts and were ICP-scored, grouped per person in the `engagers` response field (`items` stays [] on this branch). Actionable queue = scored_passed persons (`total_pending` counts exactly those); near misses (scored_failed, with scores) are display-only context and excluded from total_pending. CHECK `in_motion` BEFORE acting: it flags replied / meeting_booked / open_deal / non-terminal-plan persons — acting on them risks double outreach or resetting a deliberately deferred plan. Decide each person with manage_engagements engager_actioned / engager_dismissed / engager_reopened (person-keyed; reopen reverses a dismissal only). Act FIRST with existing tools (manage_messages send/send_linkedin for a one-off, manage_outreach action='objective_members' for an objective assignment), THEN record the decision with acted_via so attribution stays measurable. Default (no source) responses include `pending_engagers` so triage notices new engagers without an extra call. Queue-only filters are handled exp…

Get Network Identity Review Deterministic identity-quality queue for the caller's relationship graph. Reports split people, unresolved company affiliations, company aliases, and machine/shared mailboxes represented as humans. Read-only: every issue includes evidence and a typed suggested action for ``manage_network_identity_resolution``. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "issues": [ { "ref": "Ref", "kind": "Kind", "severity": "Severity", "summary": "Summary", "entity_refs": [ "string" ], "identity_refs": [ "string" ], "evidence": {}, "suggested_action": {} } ], "total": 1, "limit": 1, "offset": 1, "has_more": true, "capped": true } ```

Get Next Actions Prioritized next-action list for the user. Returns actions sorted by priority: reply responses (P1), message approvals (P2), overdue follow-ups, deals, and due/overdue tasks (P3), unenrolled high-match prospects (P4). ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "actions": [ { "action_type": "Action Type", "priority": 1, "title": "Title", "description": "Description" } ], "total": 1 } ```

Get Objective Outcomes Compare objectives on real outcomes — contacted, replied, meetings booked. A legacy outreach campaign is a MIRROR objective — pass its objective id, not the campaign id. Answers "which of these objectives actually worked" for up to 100 objectives in one call, over an explicit UTC window. Every objective you ask for comes back, including ones with no usable data — those carry `availability: "unavailable"` rather than being dropped or reported as zero, so an objective never looks like a failure when it is really just unmeasured. **Use `get_performance_metrics` instead** for funnel and time-series views of the whole account; this tool is for ranking specific objectives against each other on a like-for-like cohort. Reading the response: - **`outcome_cutoff`** is the "as of" moment. A reply or meeting counts only if it happened by then, so an objective that started last week is not punished for outcomes that have not had time to land. Keep it identical across objectives you intend to compare. - **`coverage_complete: false`** means attribution for that objective is still incomplete. Report the numbers, but do not rank on them — that is the difference between "performed badly" and "we cannot tell yet". - **`data_watermark`** is how far message and meeting ingestion has caught up. Outcomes after the watermark are not in these numbers yet. - **`computed_at`** stamps the calculation, which is worth quoting when the same window is re-run later and moves. Window rules the server enforces: all three timestamps must carry a UTC offset, `start_at < end_at <= outcome_cutoff`, and `outcome_cutoff` cannot be in the future. `objective_ids` must be unique. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "computed_at": "2023-01-01T00:00:00Z", "outcome_cutoff": "2023-01-01T00:00:00Z", "coverage_complete": true, "items": [ { "objective_id": "Objec…

Get Operator Companies List the companies the caller can act in, with summary counts. Returns every tenant where the caller has membership when they belong to at least two tenants. Drives the company switcher. This is intentionally NOT gated on operator (Vruum-staff) or owner role. The route keeps its historical ``/operator`` path for backwards-compat; switch-eligibility is a membership fact, not a staff role. The frontend derives ``canSwitch`` from the list length and ``isOperator`` from the per-company ``role`` field, so a non-operator multi-tenant user gets the switcher but not operator-only UI. Single-tenant callers get an empty list (200) rather than 404 because every authenticated client polls this route on mount. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "companies": [ { "id": "Id", "role": "Role" } ], "counts_available": true } ```

Get Outreach Review Default tool for outreach queue triage — pending messages with full context for review. Start here when reviewing or managing the outreach queue. Returns pending messages — both 'needs_draft' (unauthored, awaiting harness authoring: write via manage_messages edit) and 'draft' (authored, awaiting approve/reject), disambiguated by each item's `status` — enriched with: person context, objective instructions (tone rules, selling strategy, touch sequence), match analysis (summary, alignment points, recommended approach), company research summary, recent LinkedIn posts, conversation thread, and outreach plan state. One call gives you everything needed to author, approve, or reject. `channel_holds` reports LinkedIn sender blocks such as daily quota, provider throttling, or reconnect-required state. If `channel_holds_degraded` is true, an empty hold list is unknown rather than proof that the channel is healthy. Use content_length='full' for detailed review (capped at 5 items to prevent connection drops from oversized payloads — use offset to paginate), or 'preview' (default) for quick scanning with truncated content. Filter by objective name or ID to review a specific queue (e.g. objective='DFW CFOs'). Use message_ids to fetch specific messages by ID (comma-separated UUIDs, max 20). Bypasses sorting/pagination — returns full context for exactly those messages. Useful for subagent dispatch: pull the lightweight queue first, split into batches, then each subagent calls with its assigned message_ids. Operators: pass for_company parameter to review a specific client company. Returns (units in parentheses; scope = messages.status IN ('draft','needs_draft') for this tenant unless message_ids is set): items (list of ReviewItem, unit=messages): one entry per pending message (not per person — a person with two pending messages shows up twice). Each item: - message_id, status ('needs_draft' = author it, 'draft' = approve it),…

Get Performance Metrics Get outreach performance metrics: time-series trends and/or conversion funnel. Set view='timeseries' for daily counts of a single metric (contacts/people/replies/meetings). Set view='funnel' for aggregate conversion data: contacted->replied->met funnel with rates, reply rates by channel, and LinkedIn pipeline breakdown. Set view='both' for everything in one call. For T1s sent over time: view='timeseries', metric='contacts'. For reply rate and funnel: view='funnel'. Operators: pass for_company to get metrics for a specific client. UNIT CONVENTIONS USED IN RESPONSES Every count field is one of {messages, unique_people, plans, campaigns, days}; see the Returns block for the unit attached to each field. Note that timeseries 'contacts' and funnel.contacted are BOTH unique_people (i.e. unique people, deduped per person_id), NOT message counts. DATE-FILTER COLUMN PER METRIC (timeseries) - metric='people': filters on company_people.created_at — start_date / end_date - metric='contacts': filters on messages.sent_at (sequence_number=1 only) — start_date / end_date - metric='replies': filters on company_people.replied_at — start_date / end_date - metric='meetings': filters on company_people.meeting_booked_at — start_date / end_date reply_rates_by_channel and stage_funnel share one scope per response mode — the stage funnel is derived from the same per-channel counts, never from a separate query. Returns (selected fields, with unit + scope + date-filter annotations): view (str): Echoes the requested view. timeseries (object, when view='timeseries' or 'both'): metric (str): The metric name. data (list of {date, count}): date (str): YYYY-MM-DD. count (int): unit = unique_people for ALL four metrics (T1-sent dedupe by person; company_people rows for people/replies/meetings). funnel (object, when view='funnel' or 'both'): total_people (int, unit=unique_people, sco…

Get Person 360 Complete person context in one call. Aggregates person info, match analysis, research, activity timeline, outreach plan state, and deal info — replacing 5 separate tool calls. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "person": { "person_id": "Person Id", "current_positions": [ {} ] }, "activity": [ { "activity_type": "Activity Type", "description": "Description" } ] } ```

Get Revenue Read provider revenue and explicitly attested project finance. Views: - connection: provider connection and freshness state. - metrics: current gross MRR/ARR, net charge volume, collections and health. - evidence: recent immutable ingestion evidence for calculation drilldown. - bindings: suggested, confirmed, or rejected commercial-object bindings. - account: confirmed USD account revenue, invoices and latest recorded charge. - service_margin: finance-attested project margin for an exact closed period. - finance_workspace: current statement, finance documents and account-period labor for guided review; offset pages documents and source_ids retain selected records. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json

Import Prospects Source and import prospects — the consolidated import tool. LinkedIn people search (`payload` = the search fields): - linkedin_people_search: search PEOPLE through regular LinkedIn ({keywords, limit?}). This action does not require Sales Navigator and always uses basic mode. It returns at most 25 results and charges the capped requested limit against the shared LinkedIn daily activity budget used by reads and sends. The charge occurs before the provider call and is not refunded for zero results or an upstream failure. It does not accept company, title, headcount, list, saved-search, cursor, mode, or arbitrary seat selection. Vruum selects the current user's active connected account first and can fall back to another active tenant LinkedIn account. LinkedIn text search is best for resolving people at a known company or resolving an exact person. It is not a company-discovery source. Examples: {"keywords": "Acme VP Sales"} and {"keywords": "Jordan Lee Acme"}. - sales_nav_search: compatibility alias for existing clients. Its `mode` may be `basic` or `sales_nav`; omit it for legacy basic behavior. New regular LinkedIn searches should migrate to `linkedin_people_search`. `mode='sales_nav'` accepts {keywords, title?, company_headcount_min/max?, list_id?, saved_search_id?, limit?, cursor?} and requires a Sales Navigator subscription. Sales Navigator import actions: - sales_nav_preview: preview a Sales Nav search against your pipeline ({search?, count?, objective?}). - sales_nav_import: import people or accounts. For account imports, use {search, target: "accounts"}; `search` is a saved account search name or ID, and do not pass objective or auto_enroll. A unique match returns a job_id to poll with fetch type='job'; no_match, ambiguous, and error responses do not return a job. People imports accept {search?, count?, profiles_json?, auto_enroll?, objective?}. `profiles_json` accepts sales_nav_search output…

Inspect Pipeline Risk-first pipeline view. Returns the 5 most at-risk deals with risk scores and factors. Risk heuristics: silence (14d=+35, 7d=+20), overdue next step (+5/day max 25), no next step (+15), past close date (+20), low qualification (+10), no qualification (+5), single stakeholder (+10). Also returns pipeline health (healthy/some_risk/critical), total active deals, and total value. Operators: use X-Company-Id header for cross-company inspection. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json

Manage Account Maintain account state and impact history — the consolidated account writer. Actions: - journey_measurement_fact: record/correct/retract a sourced operator fact for an approved journey observation (no id; JourneyMeasurementFactRequest). Pin run_action_id, journey_id and independent exact-journey source_evidence_ids. checkpoint_balance describes the balance at the approved horizon; terminal_loss records its event time; impact_followup attests continuous observation with no qualifying impact from commitment through observed_at for the pinned promise. Requires explicit reviewed_source_records confirmation and an owner/operator. It does not certify complete external source coverage. - customer_journey: record one sourced engagement (no id; payload is CustomerJourneyCreate: account_id, offer_id, kind, source_key, source_evidence_id and optional originating deal / trial relationship). Read fetch type=customer_impact id=account UUID first. Account UI: Impact tab. - impact_promise: record/revise a sourced promise (no id; ImpactPromiseRequest). Freeze the journey, next promise_revision, criteria, owner and verifier policy. Supply expected_claim_id from the workspace. Preserve existing SPICED context. - impact_report: report/correct/retract one criterion occurrence (no id; ImpactObservationRequest). Use the exact claim_id and current predecessor. attribute_sources_to_journey=true explicitly attributes matching account evidence to THIS result; it never rewrites the original source. Show this assignment to the user. Customer confirmation needs a matching inbound source, person and quotation. A model's assertion is not confirmation. - impact_verify: verify the exact saved observation (no id; ImpactVerificationRequest). Obtain the user's explicit verification decision; recording a report is not permission to verify it. Current tenant membership, frozen verifier policy and source validity are rechecked by the same REST path…

Manage Content Draft, schedule and publish LinkedIn content — the consolidated content writer. Content actions (default kind; id = post UUID unless noted): - draft: create a post draft (no id; `payload` = {content, topic_tags?, scheduled_at?, author_user_id?, author_identity?, external_link?, attachment_creative_id?}); bulk via `items`. - edit: update a draft's content/tags/identity/link/attachment (`payload` = the fields to change: content?, topic_tags?, author_identity?, external_link? — empty-string external_link clears it; attachment_creative_id? — explicit null DETACHES, absent key leaves it untouched). - schedule: set the publish time (`payload` = {scheduled_at}). A row-persisted attachment publishes with the scheduled post. - publish: publish the post now (no payload; the retired publish-time creative_id param is rejected with the pointer to edit-attach). - delete: remove a draft from the calendar (drafts only — published posts are not deletable here). - draft_post: never generates prose — backend generation is removed (VRU-676, permanently). Always returns author-in-harness guidance: write the post yourself and submit via draft, then schedule/publish (no id; `payload` = {topic?, content_type?, author_user_id?}). Attachments (VRU-726) — document (PDF carousel), image, or video, ONE contract, persisted on the row (schedulable + reviewable). Golden path for a PDF, entirely via MCP: 1. manage_content kind='ad' action='store_creative' payload={filename:'my-deck.pdf', size_bytes:<n>, content_type:'application/pdf'} → returns upload_url 2. curl --fail-with-body -T my-deck.pdf '<upload_url>' 3. store_creative again with payload={creative_id:'<id>'} → validates (small assets can skip 1-3: payload={asset_base64:'<b64>'}) 4. manage_content action='draft' payload={content:'<caption>', attachment_creative_id:'<id>'} 5. get_content_review post_ids=['<post_id>'] → OPEN attachment_url and review the actual file…

Manage Deal Create and manage deals through the pipeline — the consolidated deal writer. Actions (id = deal UUID): - create: open a deal (no id; `payload` = {deal_name, person_id?, company_id?, deal_source? (outbound|inbound|referral|manual|imported; default manual), terms?, stage?, pipeline_id?, stage_id?, close_probability?, notes?}). `terms` is the deal's money record: {offer_id?, amount_minor?, currency?, billing_period?, quantity?, agreed?} — amount_minor is the net price PER BILLING PERIOD, per unit, in the currency's MINOR units (1,800.00 USD/month = 180000); billing_period one_time|monthly|quarterly|annual (recurring periods carry an annual contract value, one_time is a project total); the offer supplies currency and period when omitted; agreed=true only when the customer agreed the price (an agreed, won deal becomes committed revenue, an estimate never does). Omit terms to let the value agent estimate. `pipeline_id` and `stage_id` must be supplied together; bulk via `items`. - update: patch deal fields (`payload` = any of deal_name, terms (partial: only the keys given change), close_probability, expected_close_date, next_step, notes, stage, …). - stage: advance/move the deal — sugar for update; `payload` must include {stage}. - qualify: extract the customer's SPICED record from the deal's conversations and write the Customer Impact record; MEDDIC is derived from it (no payload). - impact_commitment: record the deal's Customer Impact (Revenue Architecture SPICED) as a claim: payload {situation?, pain?, impact? {rational? {metric, baseline, target, unit, by}, emotional?}, critical_event? {kind: compelling|critical|mandatory, due|milestone, consequence}, decision? {criteria, process, decider, champion, decider_person_id, champion_person_id}, first_impact_by?, beneficiary_person_id?, offer_id?, statement?}. Gaps fill from the standing record and MEDDIC; the record supersedes the standing one and earns its status…

Manage Engagements Triage the LinkedIn engagement queue — the consolidated engagement writer. Actions (id = engagement UUID; arrays route natively — the underlying endpoint is bulk-shaped): - approve: approve engagement(s) for sending (`payload` optional extras, e.g. {polish_provenance}). - edit: replace an engagement's content (`payload` = {content, content_mode?, reaction_type?}). - skip: discard engagement(s) — the queue's reject path (no new engagement is generated). - draft_comment: queue a comment on a LinkedIn post for AUTHORING (creates a needs_draft entry — write the comment via edit, then approve; no id; `payload` = {post_text, post_id, author_name?, person_id?, tone?, …}). Bulk: approve/edit/skip take id arrays natively (max 100) with the endpoint's own per-engagement results. Payloads are validated by the underlying route's schema. Prose gate: approve and edit re-lint the content server-side and can return error_code='prose_gate_blocked' with structured `failures[].fix`. `payload` accepts `reason` (corpus note), `override_reason` (taste override — proceeds despite block failures, logged to the corpus; honored only for owner/operator roles on the tenant, otherwise ignored and the gate blocks normally), and `client_rules_version` (responses flag `rules_changed` when the server's rules differ). Pre-check drafts cheaply with check_prose. ENGAGER DECISIONS (VRU-721 — id = PERSON UUID, not an engagement id): - engager_actioned: records a decision already executed via manage_messages / manage_outreach — performs no outreach itself. `payload` = {acted_via?: {objective_id | message_id}, note?}. Order matters: act FIRST (manage_outreach objective_members to add to an objective, or manage_messages send/send_linkedin for a one-off — the send returns the message_id), THEN record with acted_via so the engager attribution funnel stays measurable. Without acted_via the response carries an `unattributed` warning. Actioning a sub-70 near mi…

Manage Kb Maintain the knowledge base — the consolidated KB writer. Actions (id = document UUID): - upsert: create or update a document (no id — the payload's `name` is the upsert key; `payload` = {name, content, doc_type?, summary?, metadata?}); bulk via `items`. - delete: permanently delete a document. DESTRUCTIVE. - reindex: rebuild a document's search index (no payload). Bulk: delete/reindex take id arrays (server-side loop, per-item status — partial failure reported per item, never silent; max 100). Payloads are validated by the underlying route's schema. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json

Manage Messages Triage and edit outreach messages — the consolidated message writer. Actions (id = message UUID unless noted): - approve: mark a draft READY TO SEND. Sending happens asynchronously and respects the objective's designed schedule plus a per-person cooldown — approval may SCHEDULE rather than fire immediately. The response's `processing_state` says which ('queued_for_send', 'scheduled', 'held_for_channel', or 'channel_state_unknown'). A hold/unknown state includes machine-readable `channel_hold` quota/reconnect feedback and `send_not_before` when it auto-resumes; a scheduled/held message is NOT lost and must NOT be re-approved or re-drafted (get_outreach_review shows `channel_holds`, the plan's `plan_next_action_at`, and `approved_pending_send_count`). An id ARRAY routes to the native bulk endpoint with per-message results. - reject: reject a draft (array → native bulk, same as approve). - edit: replace subject/content (`payload` = {subject?, content?}). Scalar id ONLY — one call per message (an id array is rejected; sending identical content to many people is not a supported flow). Optional `attachments` sets the media sent with this draft (linkedin_inmail / linkedin_message / email only): a list where each item is a new upload {content_base64 (raw base64, no data: prefix; PNG/JPEG/GIF/ WebP/PDF, 10MB max), filename} OR {storage_path} to keep one the draft already has (from get_outreach_review). Omit = leave unchanged, [] = remove all, max 5. Attachments on any other channel are rejected. - regenerate: return the message to the authoring queue (status becomes needs_draft, content cleared) — author the replacement at triage via edit (no payload); id array loops with per-item status. Works on draft, rejected, AND failed rows — regenerate is the recovery path for a send the provider bounced (attachments survive; re-author, then re-approve). The row gets a FRESH 14-day authoring window; the response's expi…

Manage Network Identity Resolution Preview or apply one durable identity-resolution decision. ``commit=false`` is mandatory preview mode and performs no write. Re-submit the reviewed action with ``commit=true`` to merge prospect rows, merge one owned source identity, add/remove a company affiliation, or classify an email mailbox. Decisions are tenant-scoped, attributed to the caller, and survive future syncs. Required active-projection rebuilds run asynchronously. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "status": "Status", "change": {}, "next_actions": [ "string" ] } ```

Manage Outreach Start and steer outreach plans — the consolidated outreach writer. Actions: - start: enroll a person in outreach. id = PERSON UUID (scalar starts one plan; an id ARRAY routes to the native bulk-start endpoint). `payload` optional: {max_touches?, allowed_channels?} — applied to every started plan. Enrollment always schedules the first action immediately; a `start_immediately` key is ignored (forced true). For researched/discovered prospects, call manage_person action=save_discovered first with a strong current-company binding and start only when its response has `company_bound=true` and the quality gates passed. Never use start to bypass an unresolved or name-only company save. - plan_override: record a user override on a plan (id = plan UUID; `payload` = the override fields). - channels: legacy plan-local policy action. It returns 409 `objective_policy_owned`; update the objective policy or use `plan_override` for one touch. - trigger_touch: queue the plan's next touch now (id = plan UUID; no payload). Refused with a structured 409 when the plan's pending approved email cannot send now: `email_daily_cap_reached` (the conversation's owning mailbox — or, for a first email, the sender pool — is at its daily cap; the error carries the capacity numbers, when capacity resets, and when the plan retries automatically) or `thread_mailbox_unavailable` (the owning mailbox is disconnected, resting, or excluded — reconnect it; another mailbox is never substituted into an existing conversation). A success here means the touch is genuinely queued, not that it may silently re-defer. - pause / resume: pause or resume a plan (id = plan UUID). Resume re-arms the cold sequence: approved cold messages release and the next step queues. A plan that a human reply paused refuses with 409 `plan_paused_by_reply`, carrying the latest reply, the pending cold messages, and the last step fired. Never resume to release a reply:…

Manage Person Create and manage people in your pipeline — the consolidated person writer. Actions (id = person UUID unless noted): - create: add a person manually (no id; `payload` = the manual-person fields, e.g. {name, company, title, email, linkedin_url, skip_research}); bulk via `items` (one payload per person). - update_contact: override contact fields (`payload` = contact overrides). - set_position: set the primary position (`payload` = position fields). - note: add a timeline note (`payload` = {body}). - log_interaction: log a manual touch that happened outside an automated sequence — a call (with disposition + what was said), or an email/LinkedIn/other touch made elsewhere. `payload` = {interaction_kind: call|email|linkedin|meeting|other, direction?: outbound|inbound, summary?, disposition? (calls only), occurred_at? (ISO, backdatable), deal_id?}. Lands on the person's timeline attributed to you (performed_by_user_id). - archive: soft-delete one or many people — stops outreach plans and rejects pending drafts (id or id array; no payload). DESTRUCTIVE. - unarchive: restore archived people (id or id array; no payload). - meeting_booked: mark a meeting booked with this person (`payload` = {idempotency_key: UUID}; reuse it when retrying the same booking). - save_discovered: THE creator — save a researched prospect into the pipeline, atomically (no id; bulk via `items`). Two shapes: NEW prospect: `payload` = {person: {first_name, last_name, linkedin_url|email, company_id (from research action=save_company) or company_name plus company_domain/company_website/company_linkedin_url, ...research fields}, assessment: {match_score 0-100, match_summary, alignment_points?, concerns?, why_now?, recommended_approach?, overall_confidence?, scored_by?}, objective_id or assessment_objective_id}. Person + research + pipeline membership land in ONE transaction — a rejected or failed save persists nothing. EXISTING person: `payload` = {p…

Manage Relationship Action Draft, approve, and record the outcome of ONE warm-introduction attempt. A "relationship action" is a single attempt to reach a target person *through a mutual connection* rather than by contacting them directly: asking a colleague for an intro, checking whether a connector actually knows them, or requesting an entry into their company. `find_warm_path` discovers those routes and never writes; this tool is the only way to act on one. **Use this instead of the direct-outreach tools when the path runs through a person.** `manage_outreach` and `manage_messages` send to the target themselves; `manage_engagements` handles reactions and comments on content. This tool messages the *connector*. **Nothing here auto-sends.** Every attempt walks a state machine you drive one call at a time: `draft` creates it from a `result_ref` returned by `find_warm_path`, then transitions approve the exact message text, confirm that you sent it yourself outside Vruum, classify how the connector replied, record the final outcome, or cancel. The response's `approval_required` and `next_actions` fields tell you which transitions are legal right now — read them rather than guessing. Two consistency rules the server enforces: - **`draft` is idempotent on `client_request_id`.** Reuse the same value when retrying a draft; a new value creates a second attempt. - **Every transition needs `expected_version`.** A stale version means someone else moved the attempt and yours is rejected rather than silently overwriting — re-read the attempt and retry. A `409 route_stale` on draft means the underlying relationship evidence changed since it was reviewed; re-run `find_warm_path` and draft from a fresh `result_ref`. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "status": "Status", "attempt": { "ref": "Ref", "relationship_owner_user_id": "Relationship Owner User Id", "ac…

Manage Revenue Manage revenue connections and explicitly reviewed project finance facts. Actions: - service_margin_statement: record an explicitly reviewed finance statement (journey, closed period, earned-revenue/cost lines, canonical labor IDs, source documents, coverage, confirmation; corrections name the prior receipt). - connect: return the Stripe App OAuth URL ({destination, livemode}). - reconcile: enqueue an idempotent provider scan ({idempotency_key, object_family}). - replay: retry one failed evidence record (id = evidence record UUID). - decide_binding: confirm or reject one suggestion (id = binding UUID, payload = {decision}). - disconnect_preview: return a short-lived nonce and exact retention impact. - disconnect: destroy delegated credentials using that nonce ({preview_nonce}); historical ledger evidence is retained. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json

Manage Settings Update company configuration — the consolidated settings writer. Actions (no ids — settings are singletons per company): - profile: update the company profile / ICP (`payload` = the profile fields; this steers research match scoring). If supplied, `industry` must be one CanonicalIndustry value: Agriculture, Construction, Consumer Goods, Consumer Services, Education, Energy & Utilities, Financial Services, Government, Healthcare, Hospitality & Travel, Legal Services, Manufacturing, Marketing & Advertising, Media & Entertainment, Nonprofit, Professional Services, Real Estate, Retail & E-commerce, Software & Technology, Staffing & Recruiting, Telecommunications, Transportation & Logistics, Wholesale & Distribution, or Other. Provider labels and Unspecified are rejected. - auto_fill: AI-fill the company profile from the website (`payload` optional: {website_url?}; returns a job to poll via fetch type='job'). - automation: update outreach automation settings (`payload` = the automation fields). - marketing: update LinkedIn marketing settings (`payload` = the marketing fields). - cta_link: manage call-to-action links (`payload` = {action: create|update|delete, cta_link_id?, name?, url?, cta_type?, is_active?}). - offer_create: add a live offer to the catalog objectives sell from (`payload` = {name, list_price_minor, currency?, billing_period?, description?}; prices are minor units). - offer_update: edit a live offer (id = offer UUID; `payload` = any of those fields). - offer_retire: retire an offer no live objective sells (id = offer UUID; no payload); the name frees for a new live offer. - hubspot_sync_settings: set the custom HubSpot contact properties to mirror into company_people.custom_fields (`payload` = {extra_contact_properties: [...]}); CHANGING the list auto-enqueues a full backfill so existing contacts pick up the new attributes. - hubspot_backfill: kick a full HubSpot re-pull for this company (owne…

Research Run prospect/company research and save the results — the consolidated research tool. - preview_gaps: READ ONLY assignment, no research or spend. id=objective UUID; payload={subjects:[{type,person_id?,company_id?,deal_id?}], question_ids?, stage?, use_public_web?:true, use_history?:false}. Up to 20 subjects and 40 unique gaps. Reuses current account answers across people. Equivalent reviewed fact definitions also reuse original observations across objectives when their subject, schema, sources, quality and freshness match. Reused answers retain original evidence IDs; do not save duplicate copies. Read gaps, question definitions, source permissions and limits before choosing work. - stop_gaps: id=objective UUID, payload={action_id}. Stop future calls and answer writes. Already sent provider work can finish. - propose_gaps: same input; saves an Action without executing research. - approve_gaps: id=objective UUID, payload={action_id}. Only after the user approves that exact saved assignment. Starts bounded Vruum research. Poll fetch research_run id=action UUID. Never repeat approval to retry. For research on YOUR compute, use preview_gaps, fetch research_sources, your permitted tools, then save_answer. Do not approve Vruum research as a substitute for external research. Your harness pays its own compute. Use the exact subject, question ID and definition fingerprint from the assignment. Public URL excerpts remain reported. Never assert customer confirmation without an explicit operator attestation. - save_answer: record one answer for a saved objective research question (id = objective UUID; payload = {idempotency_key, question_id, definition_fingerprint, subject: {type, person_id?, company_id?, deal_id?}, state: answered|unknown|unavailable, value, source: {kind, reference?, excerpt, observed_at}, note?, supersedes_evidence_id?}). Read the question and answer_schema through fetch research_answers first. Source kinds:…

Search Polymorphic read-only search across your Vruum workspace. One tool for every list/queue/search read. Pass `type` to pick the entity: people (your pipeline — keyword `query`, batch dedup array, or list-mode `filters`), companies (company-domain contact search for decision-makers — requires filters.domain), directory_people (the shared people directory — requires filters.query), and directory_companies (the shared company directory — filters.query?, filters.industry?, or both; industry is the canonical enum, including Unspecified for missing source data). Directory results contain contact/company/freshness fields only, never another tenant's CRM state. Other types are deals, objectives, messages (outreach queue), engagements (LinkedIn engagement queue), content (LinkedIn content calendar), claims (the hypothesis ledger: falsifiable beliefs with evidence-backed confidence — filter by status or scope; render one with fetch type='claim'), kb (knowledge-base search), skills (published skills), cta_links, warm_paths (open targets that have a warm intro path — see find_warm_path for one target), relationship_attempts (the durable action timeline shared with the Relationships workspace). All types except `companies` read internal, tenant-scoped data only. Pagination (`limit`/`offset`) is supported for people (list mode), deals, messages, engagements, warm_paths, and relationship_attempts; other types reject it. Results are returned under `{type, results}` with each entity type's native payload shape. Objective routing: use `type='objectives'` here to list objectives (newest-moved first; filters.status, filters.mirror). To read one objective by UUID with its live pins and members count, use `fetch` with `type='objective'`. To create, update, clone, retire, pause, launch, or manage objective members, use `manage_outreach`. A paused objective must pass forecast review and launch approval before it becomes active again. ### Responses: **200**: Successful Response (…

Skill Invoke or publish Vruum skills — the consolidated skill tool. Actions: - invoke: fetch a skill's executable body for inline execution (id = skill UUID or name; no payload). Follow the returned instructions in your current context. - publish: publish or update a skill (no id; `payload` = {body, scope?, metadata?, supporting_files?} — `body` is the full skill markdown with frontmatter). To browse skills use search type='skills'; to read one without executing it use fetch type='skill'. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json