API reference

Create the project boundary that scopes source material, criteria, prospects, forms, drafts and responses.

POST /v1/call/op_create_project
{
  "inputs": {
    "client_name": "Example",
    "name": "Example"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Store immutable email, note, document or transcript artifacts with hashes and provenance.

POST /v1/call/op_ingest_source_material
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "artifacts": [
      {
        "kind": "email",
        "content": "content"
      }
    ]
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Pure read that snapshots artifact evidence and parse warnings; it makes no targeting decision.

POST /v1/call/prep_for_define_target_criteria
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Persist an editable, versioned target-criteria proposal for a later approval to attest against.

POST /v1/call/op_create_target_criteria
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "criteria": [
      {
        "dimension": "title",
        "values": [
          "values"
        ],
        "priority": "must"
      }
    ]
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Pure read of the exact criteria version, source citations and prohibited-targeting flags.

POST /v1/call/prep_for_approve_target_criteria
{
  "inputs": {
    "criteria_version_id": "00000000-0000-0000-0000-000000000000"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Record an approve/reject decision on one immutable criteria version, attributed to the acting actor (human or named AI) with schema-validated evidence.

POST /v1/call/op_approve_target_criteria
{
  "inputs": {
    "criteria_version_id": "00000000-0000-0000-0000-000000000000",
    "verdict": "approve",
    "rationale": "rationale"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Compile a capability-aware Google-first query plan from approved criteria without searching.

POST /v1/call/prep_for_plan_lead_search
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "criteria_version_id": "00000000-0000-0000-0000-000000000000"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Persist a reproducible query plan; the acting actor's acceptance or edits are recorded as an attributed, evidence-backed decision.

POST /v1/call/op_create_search_plan
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "criteria_version_id": "00000000-0000-0000-0000-000000000000",
    "provider": {
      "kind": "google",
      "search_mode": "web"
    },
    "query_variants": [
      {
        "query": "query"
      }
    ]
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Execute an approved lead-search plan. Google web search is the only enabled MVP provider.

POST /v1/call/op_discover_leads
{
  "inputs": {
    "search_plan_id": "00000000-0000-0000-0000-000000000000"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Deduplicate and annotate prospects with evidence, suppression state and criterion matches.

POST /v1/call/prep_for_review_prospects
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Record a yes/maybe/no decision per prospect, attributed to the acting actor with evidence. No deletes: rejected prospects remain attributable.

POST /v1/call/op_review_prospects
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "decisions": [
      {
        "prospect_id": "00000000-0000-0000-0000-000000000000",
        "verdict": "yes",
        "rationale": "rationale"
      }
    ]
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Search Exa for LinkedIn people (+ the existing panel), dedupe by identity, store each in the global panel, link them to the project as 'candidate', and RANK by a relevance score — Exa's within-query rank DOMINATES (its top-10 surface at the top; each result carries `rank` + `source_query`), keyword fit is a secondary steer, rank-less panel token-matches are capped below clean top Exa hits, and retired/student/homonym penalties sink noise (each candidate carries `flags` for the reviewer). BEST-USE PLAYBOOK: (1) write each query as a PERSON not a topic — 'master plumbers who install digital mixing valves', not 'digital mixing valves'; (2) Exa caps ~100/query and does NOT paginate, so get volume from MANY facet-varied queries — fan a broad persona by STATE/DISTRICT, a NICHE persona by descriptive TITLE — and the op dedupes; (3) use ~25 results/query (default), not 100 — relevance is front-loaded; (4) pass exclude_terms for known homonyms. Expect ~50-70% strong matches, so ALWAYS review (candidate→matched) before outreach. Returns full profiles + real Exa cost.

POST /v1/call/op_find_potential_participants
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "queries": [
      "queries"
    ]
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Resolve work emails for one or more recruits IN PARALLEL through a gated pipeline: Exa grounded answer (exact published email + the company's DOCUMENTED format + mail domain, assembled deterministically when no exact address exists) → hard gates (MX/deliverability, no role accounts like info@, no freemail; a gate kill returns unresolved with the reason in `flags`) → free SMTP RCPT verification (never sends; auto-disabled where port 25 is blocked). `confidence` is COMPUTED from `checks` (mx/name_match/format_consistent/...), never the LLM's self-report; `corroborated` means the local part matches THIS person's name. Cached unless force:true. Returns per-recruit results + total cost. Run it ON DEMAND for the people you're actually pursuing. An evidence-only Parallel fallback (~$0.005/run) automatically covers anyone the fast pipeline leaves unresolved.

POST /v1/call/op_resolve_participant_contact
{
  "inputs": {
    "recruit_ids": [
      "recruit_ids"
    ]
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Record a researcher's per-participant verdict for ONE project: matched, maybe or rejected (+ optional comment), attributed to the acting actor. This is the approve-the-matches gate. Reversible — call again to change a verdict. A rejection is scoped to this project; the recruit stays in the panel for others.

POST /v1/call/op_set_participant_status
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "updates": [
      {
        "recruit_id": "00000000-0000-0000-0000-000000000000",
        "status": "matched"
      }
    ]
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Save one outreach draft (subject + body + optional link) for a batch of participants in a project. The text is a MERGE TEMPLATE — tokens like {{first_name}}, {{company}}, {{title}}, {{link}} are filled per recruit from their profile; a token with no value is left blank and reported. One draft per (project, recruit); re-saving replaces it. It never sends mail.

POST /v1/call/op_add_outreach_draft
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "recruit_ids": [
      "recruit_ids"
    ],
    "subject": "subject",
    "body_text": "body_text"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Build a candidate one-to-three-question form context and renderer feasibility assessment.

POST /v1/call/prep_for_configure_qualification
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "criteria_version_id": "00000000-0000-0000-0000-000000000000",
    "transport": "hosted_link"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Create an immutable form version whose approval is attributed to the acting actor with schema-validated evidence. Hosted links are MVP; Gmail AMP remains gated.

POST /v1/call/op_set_qualification_form
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "title": "Example",
    "transport": "hosted_link",
    "questions": [
      {
        "prompt": "prompt",
        "type": "single_select"
      }
    ]
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Return review-approved prospects, form state, suppression flags and prior drafts/replies.

POST /v1/call/prep_for_draft_outreach
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "form_id": "00000000-0000-0000-0000-000000000000"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Persist versioned email content tied to a prospect and qualification form; it never sends mail.

POST /v1/call/op_draft_outreach
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "form_id": "00000000-0000-0000-0000-000000000000",
    "drafts": [
      {
        "prospect_id": "00000000-0000-0000-0000-000000000000",
        "subject": "subject",
        "body_text": "body_text"
      }
    ]
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Return the exact content, recipient provenance, suppression state and form renderer status.

POST /v1/call/prep_for_approve_outreach
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Record an approve/reject decision for every outward-facing message, attributed to the acting actor with schema-validated evidence.

POST /v1/call/op_approve_outreach
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "decisions": [
      {
        "draft_id": "00000000-0000-0000-0000-000000000000",
        "verdict": "approve",
        "rationale": "rationale"
      }
    ]
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Narrow public endpoint using an opaque, expiring, one-time delivery token. It is not a general MCP browser call.

POST /v1/call/capture_hosted_form_submission
{
  "inputs": {},
  "dry_run": true
}

Webhook/poll worker ingestion keyed by Gmail message ID; mailbox-wide trawling is out of scope.

POST /v1/call/ingest_gmail_reply
{
  "inputs": {
    "delivery_id": "00000000-0000-0000-0000-000000000000",
    "gmail_message_id": "00000000-0000-0000-0000-000000000000"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Correlate form and targeted Gmail replies to prospects, drafts and qualification versions.

POST /v1/call/prep_for_review_responses
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Record a qualify/decline/follow-up/opt-out decision, attributed to the acting actor with evidence. Qualified people are handed to Vidlet for scheduling.

POST /v1/call/op_triage_responses
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "decisions": [
      {
        "response_id": "00000000-0000-0000-0000-000000000000",
        "verdict": "qualified",
        "rationale": "rationale"
      }
    ]
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Create a named survey inside a project. A project may hold many surveys; the survey is the boundary reusable questions attach to.

POST /v1/call/op_create_survey
{
  "inputs": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "name": "Example"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Add a reusable question primitive to a survey — a prompt, an ordered number, a declared answer_type and a free-form answer_mode (text box, slider, date-range, dropdown — anything) plus arbitrary config. Call repeatedly to build the survey.

POST /v1/call/op_create_survey_question
{
  "inputs": {
    "survey_id": "00000000-0000-0000-0000-000000000000",
    "prompt": "prompt",
    "question_number": 1,
    "answer_type": "answer_type",
    "answer_mode": "answer_mode",
    "required": true
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Set a survey active or closed. A closed survey rejects new questions, embeds and answers; reopen it to resume. Freezes a survey once you start fielding it.

POST /v1/call/op_set_survey_status
{
  "inputs": {
    "survey_id": "00000000-0000-0000-0000-000000000000",
    "status": "active"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Mint (or return) the survey's stable Rubicon-hosted public link — no email required. Anyone with the link fills the hosted form (or the survey's custom page) and answers stream in with their self-entered email. regenerate:true revokes the old link and mints a new one.

POST /v1/call/op_publish_survey
{
  "inputs": {
    "survey_id": "00000000-0000-0000-0000-000000000000",
    "expires_in_days": 90,
    "regenerate": false
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

Attach a custom-designed HTML page to a survey; Rubicon hosts it at the survey's public/form links in place of the default renderer. Contract: the page submits to the RELATIVE URL 'form-submit' with fields q<question_number> (+ respondent_email on shared links). Empty page_html clears back to the default.

POST /v1/call/op_set_survey_page
{
  "inputs": {
    "survey_id": "00000000-0000-0000-0000-000000000000"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

PUBLIC ingress: anyone (a hosted form or an embedded email link) may submit one validated answer, which streams into the dedicated survey-answers store. Intentionally outside the actor-auth model; not callable as an MCP tool.

POST /v1/call/op_answer_survey
{
  "inputs": {
    "survey_id": "00000000-0000-0000-0000-000000000000",
    "question_number": 1,
    "answer": "example"
  },
  "idempotency_key": "REPLACE-WITH-A-UNIQUE-KEY-PER-CALL",
  "dry_run": true
}

List the apps you can see — each with its live URL, status and version.

POST /v1/call/list_apps
{
  "inputs": {},
  "dry_run": true
}

One app's metadata: status, active version, owner and description.

POST /v1/call/get_app
{
  "inputs": {},
  "dry_run": true
}

Everything an editor needs before changing an app: source, contract, recent activity.

POST /v1/call/get_app_context
{
  "inputs": {},
  "dry_run": true
}

Read an app's current source bundle (client + server + manifest).

POST /v1/call/get_app_source
{
  "inputs": {},
  "dry_run": true
}

An app's recent governed calls — the audit trail behind what it did.

POST /v1/call/get_app_activity
{
  "inputs": {},
  "dry_run": true
}

Every deployed version of an app, newest first (for rollback).

POST /v1/call/list_app_versions
{
  "inputs": {},
  "dry_run": true
}

Create or replace an app from source; the build typechecks against this API.

POST /v1/call/deploy_app_source
{
  "inputs": {},
  "dry_run": true
}

Patch an existing app in place and cut a new version.

POST /v1/call/update_app_source
{
  "inputs": {},
  "dry_run": true
}

Move an app between development / beta / production.

POST /v1/call/set_app_status
{
  "inputs": {},
  "dry_run": true
}

Instantly restore a previous version of an app.

POST /v1/call/rollback_app
{
  "inputs": {},
  "dry_run": true
}

Make an app's staged candidate the live version (atomic compare-and-set).

POST /v1/call/promote_app_version
{
  "inputs": {},
  "dry_run": true
}

Drop an app's staged candidate without touching the live version.

POST /v1/call/discard_app_version
{
  "inputs": {},
  "dry_run": true
}

Drive an app's own routes server-side to prove it works end-to-end.

POST /v1/call/exercise_app
{
  "inputs": {},
  "dry_run": true
}

Read a value from an app's durable key/value state.

POST /v1/call/capsule_state_get
{
  "inputs": {},
  "dry_run": true
}

Write a value into an app's durable key/value state.

POST /v1/call/capsule_state_set
{
  "inputs": {},
  "dry_run": true
}

The inference models available to apps, plus the current default.

POST /v1/call/list_models
{
  "inputs": {},
  "dry_run": true
}