MCP tool reference

The MCP server at /api/v1/mcp offers 141 tools: 79 read, 54 write and 8 destructive (they remove or stop something). tools/list shows only the tools your credential's scopes allow, and tools/call checks the scope again before it runs the route's own handler, so role checks, validation, compliance gates and the audit log apply exactly as for an HTTP request.

Each tool is one API route. Arguments become path parameters, then query parameters (GET) or the JSON body. A 2xx answer comes back as structuredContent; any other status comes back as a tool error {status, detail}.

Personal assistant

whoami

Who am I? (workspace and access) · read · scope any key · GET /api/v1/assistant/context

Start here. Who this connection acts as: the user (name, email), the workspace (name, time zone, current local time and date), the user's role and the credential (an API key or a connected app) with its scopes, i.e. which tools will work. Use the local date and time for 'today', 'this morning' or 'tomorrow'.

get_daily_briefing

Daily briefing · read · scope any key · GET /api/v1/assistant/briefing

One compact summary for 'what happened?' and 'what needs me?': activity since since (default the last 24 hours; new leads, emails sent, replies by category, calls by outcome, meetings booked), what waits for the user (AI email drafts and reply drafts to review, replies with an open draft answer, calls where the lead asked for a person) and today's meetings, AI callbacks and calls in the workspace's time zone. Lists hold at most limit items (default 5). Sections the connection's scopes can't read are left out and named in omitted. Prefer this over many list calls.

list_agenda

Meetings and callbacks · read · scope calls:read · GET /api/v1/agenda

Booked meetings and scheduled AI callbacks (calls the voice agent will place because the lead asked to be called back) between from and to (ISO date-times; default now to 7 days ahead, at most 92 days), soonest first, each with its lead, time, title and note. Filter with kind (meeting or callback, repeatable).

Meeting prep

get_meeting_prep

Meeting prep · read · scope calls:read · GET /api/v1/meetings/{meeting_id}/prep

A booked meeting (meeting_id, from list_agenda) and the Meeting copilot's prep for it: who they are, why they replied, prior emails, calls and notes, open questions, a suggested agenda, talking points and risks, with the records it read. prep is null until one is written with prepare_meeting.

prepare_meeting

Prepare a meeting · write · scope calls:write · POST /api/v1/ai/meeting-prep

Write (or refresh) the prep of a booked meeting (meeting_id) from our own records (emails, replies, calls, notes, research, memory) and the workspace's prep instructions. Internal only: nothing is sent. One AI call within the free-tier budget (503 when used up); 409 agent_paused while the Meeting copilot is paused.

draft_email

Draft an email for review · write · scope replies:write · POST /api/v1/leads/{lead_id}/draft-email

Draft a new email to a lead (lead_id, subject, plain-text body; optionally the mailbox_id to send from). It is NOT sent: it goes into the Approvals review queue as a pending reply draft (kind compose) for a person to approve and send in ZeroReach. Refused with 409 when the lead can't be emailed (no address, suppressed, opted out, no consent basis); a temporary limit (contact pressure) still saves the draft and says send_not_before. warnings lists what will block the send (e.g. no connected mailbox, no postal address for the unsubscribe footer). Check can_contact first if unsure.

The workspace's business profile and mailboxes

get_workspace_profile

Business profile · read · scope workspace:read · GET /api/v1/workspaces/current/profile

The workspace's business profile: website, company description, offer, ideal customer profile (icp: industries, company sizes, buyer titles, regions, pain points), tone, the AI persona's name and the postal address used in email footers. Company discovery and the AI writer use it.

update_workspace_profile

Update business profile · write · scope admin · PUT /api/v1/workspaces/current/profile

Change some fields of the business profile (only the fields given): website, company_description, offer, icp (replaces the whole ICP), tone, persona_name, postal_address. Admins only.

draft_company_profile

Draft profile from website · read · scope admin · POST /api/v1/ai/profile-draft

Suggest the company description, offer and ICP from the company website's pages already read into the knowledge base (website, default the profile's). Nothing is saved: show the suggestions, then save them with update_workspace_profile. 409 when the site hasn't been read yet (add it with add_website_to_knowledge_base); one AI call within the free-tier budget (503 when used up).

add_website_to_knowledge_base

Read a website into the knowledge base · write · scope kb:write · POST /api/v1/kb/documents/url

Crawl a website (url, same site, robots.txt honored, page-limited) into the knowledge base in the background, so the AI writer and the profile draft can use it. Returns the start page's document (document.id, status pending until the crawl is ready or failed) and the job.

list_mailboxes

List mailboxes · read · scope mailboxes:read · GET /api/v1/mailboxes

The workspace's connected email mailboxes with their state (connected, paused), daily cap and warmup. Sending needs at least one connected mailbox; connecting one happens in ZeroReach (Settings, Mailboxes).

search_leads

Search leads · read · scope leads:read · GET /api/v1/leads

List the workspace's leads, newest first. Filter by status (repeatable), company_id, owner_id, language (a code like hi or pt-BR, or a language name) or free text q (name, email, title); page with limit and the previous page's next_cursor as cursor.

get_lead

Get lead · read · scope leads:read · GET /api/v1/leads/{lead_id}

One lead with its company, contact details, status, spoken language (what its calls start in; null = the workspace default) and custom fields.

create_lead

Create lead · write · scope leads:write · POST /api/v1/leads

Create a lead. Give at least an email, a phone or a LinkedIn URL so it can be contacted; phone must be E.164 (+14155550100); language (e.g. hi, te-IN) is the language its calls start in. Duplicates (same email) are rejected with 409.

update_lead

Update lead · write · scope leads:write · PATCH /api/v1/leads/{lead_id}

Change some fields of a lead (only the fields given; null clears a field), e.g. its spoken language (hi, te-IN; null = the workspace default).

delete_lead

Delete lead (destructive) · destructive · scope leads:write · DELETE /api/v1/leads/{lead_id}

DESTRUCTIVE: delete a lead (soft delete: it disappears from lists and its enrollments stop).

get_lead_timeline

Lead timeline · read · scope leads:read · GET /api/v1/leads/{lead_id}/timeline

A lead's activity timeline, newest first: emails, replies, calls, notes, enrollments, consent changes.

add_note

Add note · write · scope leads:write · POST /api/v1/leads/{lead_id}/notes

Add a note to a lead's timeline (body; occurred_at to log something that happened earlier).

can_contact

Can contact? (compliance decision) · read · scope leads:read · GET /api/v1/leads/{lead_id}/contactability

The compliance decision for contacting a lead on a channel (email, phone, sms, linkedin) for a purpose: allowed, machine-readable reasons (suppressions, missing consent, calling window, frequency caps) and next_allowed_at. Check it before any outreach; every send and call is gated by the same rules anyway.

opt_out_lead

Record opt-out · write · scope compliance:write · POST /api/v1/leads/{lead_id}/opt-out

Record that a lead opted out of a channel (by default every channel): adds suppressions so nothing is sent or dialled to them again.

search_companies

Search companies · read · scope leads:read · GET /api/v1/companies

List the workspace's companies, newest first. Filter by free text q (name, domain), industry or country; page with cursor.

get_company

Get company · read · scope leads:read · GET /api/v1/companies/{company_id}

One company.

create_company

Create company · write · scope leads:write · POST /api/v1/companies

Create a company (409 when the domain already exists).

update_company

Update company · write · scope leads:write · PATCH /api/v1/companies/{company_id}

Change some fields of a company (only the fields given; null clears a field), e.g. its name, domain, industry, size or country. 409 when the new domain belongs to another company.

list_sequences

List sequences · read · scope sequences:read · GET /api/v1/sequences

The workspace's sequences (campaigns) with step and enrollment counts. Filter by status or q.

get_sequence

Get sequence · read · scope sequences:read · GET /api/v1/sequences/{sequence_id}

One sequence with its steps, settings and enrollment counts.

create_sequence

Create sequence · write · scope sequences:write · POST /api/v1/sequences

Create a sequence (campaign) as a draft: name, optional description and settings (time zone, send window, send days, daily cap, stop on reply; defaults to the workspace's time zone, weekdays 9-17). Add steps with add_sequence_step, then activate_sequence.

update_sequence

Update sequence · write · scope sequences:write · PATCH /api/v1/sequences/{sequence_id}

Change a sequence's name, description or settings (only the fields given). A settings change reschedules active enrollments. 409 when archived.

activate_sequence

Activate sequence · write · scope sequences:write · POST /api/v1/sequences/{sequence_id}/activate

Start a draft or paused sequence: enrolled leads get their steps from now on, inside the sending window and every compliance check. 409 without steps, without a subject on the first email, or (with email steps) without the workspace's postal address.

pause_sequence

Pause sequence · write · scope sequences:write · POST /api/v1/sequences/{sequence_id}/pause

Pause an active sequence: no step runs until resume_sequence. Nothing is lost.

resume_sequence

Resume sequence · write · scope sequences:write · POST /api/v1/sequences/{sequence_id}/resume

Resume a paused sequence; overdue steps are rescheduled from now.

add_sequence_step

Add sequence step · write · scope sequences:write · POST /api/v1/sequences/{sequence_id}/steps

Add a step to a sequence (appended, or inserted at position): channel (email, call, linkedin_task, manual_task), the wait before it (delay_days, delay_hours), and for email a subject / body template (variables like {{lead.first_name}}, {{company.name \| your team}}) and/or an ai_brief for the AI writer. 409 while leads are enrolled. Returns the sequence with all its steps.

update_sequence_step

Update sequence step · write · scope sequences:write · PATCH /api/v1/sequences/{sequence_id}/steps/{step_id}

Change some fields of a step (subject, body, AI brief, delays, variants; only the fields given). A delay change reschedules enrollments waiting on it. Use preview_sequence_step to check the result.

delete_sequence_step

Delete sequence step (destructive) · destructive · scope sequences:write · DELETE /api/v1/sequences/{sequence_id}/steps/{step_id}

DESTRUCTIVE: delete a step; later steps move up. 409 while leads are enrolled.

reorder_sequence_steps

Reorder sequence steps · write · scope sequences:write · PUT /api/v1/sequences/{sequence_id}/steps/order

Put a sequence's steps in a new order: step_ids lists every step once. 409 while leads are enrolled.

preview_sequence_step

Preview sequence step · read · scope sequences:read · GET /api/v1/sequences/{sequence_id}/steps/{step_id}/preview

A step's subject and body rendered for one lead (lead_id), with the current user as the sender.

get_sequence_mailboxes

Sequence mailbox pool · read · scope sequences:read · GET /api/v1/sequences/{sequence_id}/mailboxes

Which mailboxes a sequence sends new conversations from: its pool (mode: pool) or every mailbox of the workspace (mode: all), each with its state and whether it is in rotation.

set_sequence_mailboxes

Set sequence mailbox pool · write · scope sequences:write · PUT /api/v1/sequences/{sequence_id}/mailboxes

Limit a sequence to a pool of mailboxes (mailbox_ids; an empty list = every mailbox of the workspace again). New conversations rotate only within the pool (by rotation weight); follow-ups stay in their thread's mailbox.

list_enrollments

List enrollments · read · scope sequences:read · GET /api/v1/sequences/{sequence_id}/enrollments

The leads enrolled in a sequence, with their state and next step.

enroll_leads

Enroll leads · write · scope sequences:write · POST /api/v1/sequences/{sequence_id}/enrollments

Enroll leads (lead_ids, up to 1,000) in a sequence. Idempotent per lead. Leads that can't be contacted are skipped with a reason (contact_denied:<channel>:<reason> for suppressions or missing consent, missing_email, already_enrolled, not_found).

unenroll_leads

Unenroll leads (destructive) · destructive · scope sequences:write · POST /api/v1/sequences/{sequence_id}/enrollments/unenroll

DESTRUCTIVE: stop the given leads' enrollments in a sequence (no further steps are sent). Can't be undone; re-enrolling starts over.

list_calls

List calls · read · scope calls:read · GET /api/v1/calls

Voice calls, newest first. Filter by status, outcome, lead_id, since / until.

get_call

Get call · read · scope calls:read · GET /api/v1/calls/{call_id}

One call with its transcript, booked meetings and the post-call analysis.

list_replies

List replies · read · scope replies:read · GET /api/v1/replies

Inbound email replies with their AI classification (category, intent), newest first. Filter by category (repeatable), needs_attention, has_draft, since / until.

get_lead_research

Lead research · read · scope leads:read · GET /api/v1/leads/{lead_id}/research/latest

The latest AI research brief for a lead (company summary, signals, talking points), if one was run.

get_memory

Memory · read · scope leads:read · GET /api/v1/leads/{lead_id}/memory

What ZeroReach remembers about a lead (lead_id) or a company (company_id): current facts with confidence, open objections, relationships and recent interactions, each citing its source (timeline event, call, reply, research). text is a compact block capped at max_tokens.

get_analytics_summary

Analytics summary · read · scope analytics:read · GET /api/v1/analytics/summary

Outreach totals and rates (sent, opened, replied, bounced, calls, meetings) for a UTC day range (from / to, default the last 30 days), optionally per sequence, channel or mailbox.

get_analytics_timeseries

Analytics time series · read · scope analytics:read · GET /api/v1/analytics/timeseries

Metrics per day/week/month (interval) for a day range, optionally grouped (group_by).

start_export

Start export · write · scope exports:write · GET /api/v1/{dataset}/export

Start a background CSV/XLSX export of a list (dataset), with that list's filters in filters (e.g. {"status": ["new"]} for leads). Returns the export; poll get_export until status is succeeded, then download its download_url (signed, no key needed).

get_export

Get export · read · scope exports:read · GET /api/v1/exports/{export_id}

One background export: its status and, once built, a fresh signed download_url.

Approvals: AI email drafts and reply drafts

get_approval_counts

Approval counts · read · scope sequences:read · GET /api/v1/approvals/counts

How many AI email drafts and reply drafts are waiting for review (pending).

list_email_drafts

List email drafts · read · scope sequences:read · GET /api/v1/email-drafts

AI-written sequence emails, newest first. status=pending is the review queue; filter by lead_id or sequence_id; page with cursor.

get_email_draft

Get email draft · read · scope sequences:read · GET /api/v1/email-drafts/{draft_id}

One AI email draft: subject, body, lint warnings, the lead and the sequence step.

approve_email_draft

Approve email draft · write · scope sequences:write · POST /api/v1/email-drafts/{draft_id}/approve

Approve a pending AI email draft, optionally with a final subject / body. The sequence runner sends it at its next pass, after the usual compliance checks (suppressions, consent, send caps). 409 when the draft isn't pending or the enrollment ended.

reject_email_draft

Reject email draft (destructive) · destructive · scope sequences:write · POST /api/v1/email-drafts/{draft_id}/reject

DESTRUCTIVE: reject a pending or approved AI email draft: it is never sent and the lead's sequence enrollment stops. With regenerate: true the AI rewrites it instead, using reason as feedback (the sequence keeps running).

regenerate_email_draft

Regenerate email draft · write · scope sequences:write · POST /api/v1/email-drafts/{draft_id}/regenerate

Have the AI rewrite an email draft with your feedback (default: its reject reason); the result is a new pending revision for review. Uses the workspace's free-tier AI budget (503 when used up).

list_reply_drafts

List reply drafts · read · scope replies:read · GET /api/v1/reply-drafts

Email drafts waiting for a person, newest first: AI answers to inbound replies, post-call recap emails (kind=call_recap) and emails drafted with draft_email (kind=compose). status=pending is the review queue. Only a signed-in person approves and sends them, in ZeroReach (Approvals); you can edit (edit_reply_draft) or reject them.

edit_reply_draft

Edit reply draft · write · scope replies:write · PATCH /api/v1/reply-drafts/{draft_id}

Change a pending reply draft's body (and optionally subject) before a person reviews it. The original AI text is kept; nothing is sent.

reject_reply_draft

Reject reply draft · write · scope replies:write · POST /api/v1/reply-drafts/{draft_id}/reject

Reject a reply draft (never sent), with an optional reason.

Research, knowledge base

start_lead_research

Research lead · write · scope leads:write · POST /api/v1/leads/{lead_id}/research

Research a lead and its company now (website, news, job posts; cited hooks and an ICP fit score), optionally against an icp text instead of the workspace ICP. Uses the free-tier AI and search budgets. Answers the stored research, or a queued job (job_id: poll get_lead_research_job) when research runs in the background.

get_lead_research_job

Lead research job · read · scope leads:read · GET /api/v1/leads/{lead_id}/research/jobs/{job_id}

The status of a queued lead research job (job_id from start_lead_research); read the result with get_lead_research once it succeeded.

search_knowledge_base

Search knowledge base · read · scope kb:read · GET /api/v1/kb/search

Semantic search over the workspace's knowledge base (product docs, FAQs, case studies): the best matching passages with their source document and score.

Company discovery

start_discovery_run

Start discovery run · write · scope admin · POST /api/v1/discovery/runs

Find new companies that match the workspace ICP: web search (within the daily search budget), the given seed_urls and the companies linked from directory_urls (pages that list companies); each site is visited politely and scored. Nothing is imported until a candidate is accepted. One run at a time; a few per day.

list_discovery_runs

List discovery runs · read · scope leads:read · GET /api/v1/discovery/runs

Discovery runs, newest first, with their status, queries and counters.

get_discovery_run

Get discovery run · read · scope leads:read · GET /api/v1/discovery/runs/{run_id}

One discovery run: status, the queries run, counters (candidates_created, pages_fetched, skipped ...) and the error, if it failed.

list_discovery_candidates

List discovered companies · read · scope leads:read · GET /api/v1/discovery/candidates

Companies found by discovery, best ICP fit first, with the reasons and signals behind each score. Filter by status (new = to review), run_id or min_score.

accept_discovery_candidate

Accept discovered company · write · scope leads:write · POST /api/v1/discovery/candidates/{candidate_id}/accept

Accept a discovered company: creates the company (or links the existing one). Refused when its domain is suppressed.

reject_discovery_candidate

Reject discovered company (destructive) · destructive · scope leads:write · POST /api/v1/discovery/candidates/{candidate_id}/reject

DESTRUCTIVE: reject a discovered company; its domain is never proposed again.

Signals and research batches

list_signals

List signals · read · scope leads:read · GET /api/v1/signals

Buying signals (hiring, funding, news, tech stack, website changes), newest first, with evidence and source. Filter by company_id, lead_id (the lead's own and its company's), kind or notified.

request_signal_scan

Watch company for signals · write · scope leads:write · POST /api/v1/signals/scan

Add a company (company_id, with a domain) to the signal watch list and bring its next scan forward.

list_signal_rules

List signal rules · read · scope leads:read · GET /api/v1/signal-rules

The workspace's trigger rules: which signals notify (a webhook) or enroll the company's leads into a sequence.

start_research_batch

Start research batch · write · scope leads:write · POST /api/v1/research/batches

Research many leads (lead_ids) or companies (company_ids), or a discovery run's accepted companies (discovery_run_id), in the background within per-run caps (max_llm_calls) and the daily free-tier budgets. Poll get_research_batch.

list_research_batches

List research batches · read · scope leads:read · GET /api/v1/research/batches

Research batches, newest first, with progress and budgets used.

get_research_batch

Get research batch · read · scope leads:read · GET /api/v1/research/batches/{batch_id}

One research batch: status, progress per item status, LLM and search calls used, and why it is paused, if it is.

list_research_batch_items

List research batch items · read · scope leads:read · GET /api/v1/research/batches/{batch_id}/items

The items of a research batch in queue order, each with its status, error and quality report.

cancel_research_batch

Cancel research batch (destructive) · destructive · scope leads:write · POST /api/v1/research/batches/{batch_id}/cancel

DESTRUCTIVE: cancel a queued, running or paused research batch; items not researched yet are skipped.

get_company_research

Company research · read · scope leads:read · GET /api/v1/companies/{company_id}/research/latest

The latest research brief for a company (summary, cited facts, ICP fit score and reasons, risks), if one was run.

Notifications and search

list_notifications

List notifications · read · scope notifications:read · GET /api/v1/notifications

The key user's in-app notifications (mailbox pauses, signal rules, finished exports and research batches, disabled webhooks, completed privacy exports), unread first, with the unread count. unread_only=true for the unread ones.

search_workspace

Search workspace · read · scope leads:read · GET /api/v1/search

Search leads, companies, campaigns and calls at once by free text q (names, emails, domains, numbers); at most limit of each kind.

Full app coverage for Oro

get_workspace

Workspace settings · read · scope workspace:read · GET /api/v1/workspaces/current

The workspace: name, plan, time zone, country, default language and your role.

list_members

List team members · read · scope workspace:read · GET /api/v1/workspaces/current/members

The workspace's members with their role (owner, admin, member) and when they joined.

get_business_hours

Business hours · read · scope workspace:read · GET /api/v1/workspaces/current/business-hours

The workspace's business hours per weekday and its time zone (used for calls and handoffs).

get_calling_settings

Calling settings · read · scope workspace:read · GET /api/v1/workspaces/current/speed-to-lead

Speed-to-lead (calling new web leads at once) and whether telephony is set up.

get_voicemail_settings

Voicemail settings · read · scope workspace:read · GET /api/v1/workspaces/current/voicemail

What the voice agent does on an answering machine (hang up, leave a message) and the callback number.

get_transfer_settings

Live transfer settings · read · scope workspace:read · GET /api/v1/workspaces/current/transfer

Where the voice agent transfers a call to a person (number or SIP), when, and the ring timeout.

get_voice_capacity

Call capacity · read · scope workspace:read · GET /api/v1/workspaces/current/voice-capacity

How many calls may run at once, how many are active and how many dials are waiting.

get_calling_policy

Calling policy · read · scope compliance:read · GET /api/v1/workspaces/current/calling-policy

The calling policy in force: allowed local hours per country, quiet days and the source of each rule.

get_contact_pressure

Contact pressure limits · read · scope compliance:read · GET /api/v1/workspaces/current/contact-pressure

How often one person, company or domain may be contacted (per channel and window).

list_suppressions

List suppressions · read · scope compliance:read · GET /api/v1/suppressions

The suppression list (do-not-contact emails, phones, domains), newest first. Filter by q, kind or reason.

add_suppression

Add suppression · write · scope compliance:write · POST /api/v1/suppressions

Add an email, phone or domain to the suppression list so nothing is sent or dialled to it.

list_consents

Lead consents · read · scope compliance:read · GET /api/v1/leads/{lead_id}/consents

A lead's consent records per channel and purpose (basis, source, when, revoked or not).

get_deliverability

Deliverability · read · scope mailboxes:read · GET /api/v1/deliverability

Sending health: each mailbox's recent bounce and complaint rates and the sending domains' SPF/DKIM/DMARC checks.

list_lead_calls

Lead calls · read · scope calls:read · GET /api/v1/leads/{lead_id}/calls

A lead's voice calls, newest first, with outcome and summary.

enrich_lead

Enrich lead · write · scope leads:write · POST /api/v1/leads/{lead_id}/enrich

Fill a lead's missing contact details from the configured enrichment provider (uses its trial credits).

get_enrichment_usage

Enrichment credits · read · scope leads:read · GET /api/v1/enrichment/usage

Enrichment lookups, units and estimated cost per provider between since and until.

get_import

Get import · read · scope leads:read · GET /api/v1/imports/{import_id}

A lead import: status, counts (created, updated, skipped, errors) and the rows that failed.

commit_lead_import

Import leads · write · scope leads:write · POST /api/v1/imports/{import_id}/commit

Import a previewed spreadsheet's rows as leads with a column mapping ([{column, field, custom_key}]), deduping on email/LinkedIn/phone (dedupe: skip or update_empty_fields). 409 when already imported.

pause_enrollment

Pause enrollment · write · scope sequences:write · POST /api/v1/sequences/{sequence_id}/enrollments/{enrollment_id}/pause

Pause one lead's enrollment in a sequence (no further steps until resumed in the app).

list_exports

List exports · read · scope exports:read · GET /api/v1/exports

Background exports, newest first, with their status.

list_knowledge_documents

List knowledge base documents · read · scope kb:read · GET /api/v1/kb/documents

The knowledge base's documents (title, source, status, chunks), newest first.

add_text_to_knowledge_base

Add text to the knowledge base · write · scope kb:write · POST /api/v1/kb/documents/text

Store a title and text (an offer, FAQ answers, pricing notes) in the knowledge base for the AI writer and the voice agent.

get_ai_usage

AI usage and credits · read · scope admin · GET /api/v1/workspaces/current/ai-usage

AI credits used over the last days (7, 30 or 90), or by month with period (current or previous), by feature, model and person, with a daily series. Admins see the workspace; a member sees only their own usage.

get_ai_credits

AI credits this month · read · scope leads:read · GET /api/v1/workspaces/current/ai-credits

This month's AI credits: the allowance, used and left, the level (ok, warning, exhausted when AI is paused until the 1st), the alert thresholds reached and the caller's own monthly limit.

estimate_ai_credits

Estimate AI credits · read · scope leads:read · POST /api/v1/ai-credits/estimate

About how many AI credits a bulk job will use before starting it: action research_batch (with items, the number of leads or companies), discovery_run, or ai_column (with items, the rows an AI column runs on). Answers text (“about N credits”), what's left, and a warning when it may not fit. Mention it before proposing a research batch or a discovery run.

mark_notifications_read

Mark notifications read · write · scope notifications:write · POST /api/v1/notifications/read-all

Mark all of the user's in-app notifications read.

The light CRM: deals and pipelines

list_pipelines

List pipelines · read · scope crm:read · GET /api/v1/pipelines

The deal pipelines with their ordered stages: each stage's id, name, kind (open, won, lost), default probability and required_fields (what a deal needs before it may enter the stage). Use the stage ids with create_deal and move_deal.

create_pipeline

Create pipeline · write · scope crm:write · POST /api/v1/pipelines

Create a deal pipeline (name) with its ordered stages (name, kind, probability, required_fields); default stages when none are given.

update_pipeline_stages

Change pipeline stages · write · scope crm:write · PUT /api/v1/pipelines/{pipeline_id}/stages

Set a pipeline's whole ordered stage list (pipeline_id, stages). Keep a stage by passing its id; a stage left out is removed (refused while deals are in it). Set required_fields (value, close_date, owner_id, company_id, contacts, next_step) per stage.

search_deals

Search deals · read · scope crm:read · GET /api/v1/deals

List deals in board order with their stage, value, currency, probability, weighted value, owner, close date, company and people. Filter by pipeline_id, stage_id, status (open, won, lost; repeatable), owner_id, company_id, lead_id (a person on the deal) or q (deal or company name).

get_deal

Get deal · read · scope crm:read · GET /api/v1/deals/{deal_id}

One deal (deal_id) with its stage, value, probability, close date, next step, company and people.

get_deal_analytics

Pipeline analytics · read · scope crm:read · GET /api/v1/deals/analytics

A pipeline by stage (default the default pipeline): deal count, value and weighted value per stage, open/won/lost totals, win rate and open deals closing this month.

create_deal

Create deal · write · scope crm:write · POST /api/v1/deals

Create a deal (name) for a company (company_id) and its people (contact_ids: lead ids), with value, currency (ISO code, default USD), owner_id, close_date, probability and next_step. It starts in the default pipeline's first open stage unless pipeline_id / stage_id are given; that stage's required fields must be set.

update_deal

Update deal · write · scope crm:write · PATCH /api/v1/deals/{deal_id}

Change some fields of a deal (deal_id; only the fields given, null clears): name, value, currency, owner, close date, probability, next step, company, people (contact_ids replaces them), or its stage/pipeline. Entering a stage needs that stage's required fields (422 lists the missing ones).

move_deal

Move deal to a stage · write · scope crm:write · POST /api/v1/deals/{deal_id}/move

Move a deal (deal_id) to another stage of its pipeline (stage_id). Won and lost stages close it. Refused with the missing fields when the stage requires something the deal lacks: set them with update_deal first.

delete_deal

Delete deal · destructive · scope crm:write · DELETE /api/v1/deals/{deal_id}

Delete a deal (deal_id) with its tasks and activities; its company and people stay.

Deal room

get_deal_room

Get deal room · read · scope crm:read · GET /api/v1/deals/{deal_id}/room

A deal's room (deal_id): quote lines, discount and its approval state, totals, proposal, mutual action plan, share link state (views), signature request and the audit trail.

set_deal_quote

Set deal quote · write · scope crm:write · PUT /api/v1/deals/{deal_id}/room/quote

Replace a deal's quote (deal_id): items [{name, quantity, unit_price}] and discount_pct. A discount above the user's role limit waits for an admin's approval and doesn't apply until then. Refused while a signature request is open.

save_deal_proposal

Save deal proposal · write · scope crm:write · PUT /api/v1/deals/{deal_id}/room/proposal

Save the proposal text of a deal (deal_id, proposal). Refused while a signature request is open. Sending it for signature is done by a person in the app.

add_deal_plan_step

Add mutual action plan step · write · scope crm:write · POST /api/v1/deals/{deal_id}/room/plan

Add a step to a deal's mutual action plan (deal_id, title, owner us/them/both, due_date).

update_deal_plan_step

Update mutual action plan step · write · scope crm:write · PATCH /api/v1/deals/{deal_id}/room/plan/{step_id}

Change a plan step (deal_id, step_id): title, owner, due date, or done.

get_discount_limits

Discount limits · read · scope crm:read · GET /api/v1/deal-room/discount-limits

The largest discount each role may give without an admin's approval, and the user's own limit.

Agents hub

list_agents

List agents · read · scope agents:read · GET /api/v1/agents

The AI sales team (Prospector, Researcher, Writer, Inbox agent, Caller, ...): each agent's state (on, off, paused, coming soon), autonomy and its cap, schedule (with time zone), what pausing stops, last activity and today's count.

get_agent_activity

Agent activity · read · scope agents:read · GET /api/v1/agents/activity

Recent job runs and timeline events of the agents, or one agent, newest first (last 30 days, limit up to 200).

update_agent

Update agent · write · scope agents:write · PATCH /api/v1/agents/{agent}

Change an agent (agent key; admins only): enabled, paused, autonomy (suggest, ask_first, auto; agents that reach customers - Writer, Inbox agent, Caller, Deal desk - are capped at ask_first, refused with 422 autonomy_cap; the Writer and Inbox agent can be auto only while Email approval is none, and only by an admin in the app: this tool gets 403 human_only for that) or the Prospector's weekly schedule {days 0=Mon..6=Sun, hour} in the workspace time zone (null clears).

Forecasting and coaching

get_forecast

Sales forecast · read · scope analytics:read · GET /api/v1/analytics/forecast

Open deals with an explainable win probability (stage probability adjusted by activity, replies, meetings, next step, close date, plan progress and signature, each factor listed) and the weighted forecast by close-date month (months 1-12), with totals per currency (never converted) and per owner.

get_call_scorecards

Call scorecards · read · scope analytics:read · GET /api/v1/analytics/call-scorecards

Scorecards of recent calls (days, limit): talk ratio, questions asked, next step set, a score out of 100, coaching tips per call and for the team.

Tasks, notes and activities

list_tasks

List tasks · read · scope crm:read · GET /api/v1/tasks

Tasks, open first and soonest due first, with open and overdue counts. Filter by status (open, done), owner_id (a member id or me), lead_id, company_id, deal_id or due_before.

create_task

Create task · write · scope crm:write · POST /api/v1/tasks

Create a task (title, optional notes, due_at ISO date-time with offset, owner_id default the user) on a lead (lead_id), company (company_id) or deal (deal_id), or on its own.

update_task

Update task · write · scope crm:write · PATCH /api/v1/tasks/{task_id}

Change a task (task_id): title, notes, due time, owner, or status: done to complete it.

delete_task

Delete task · destructive · scope crm:write · DELETE /api/v1/tasks/{task_id}

Delete a task (task_id).

list_activities

List notes and activities · read · scope crm:read · GET /api/v1/activities

Notes and logged activities (coffee chats, events, referrals, calls, meetings...) on a lead (lead_id), a company (company_id, with its people's and deals') or a deal (deal_id), newest first.

log_activity

Add note or log activity · write · scope crm:write · POST /api/v1/activities

Add a note or log an activity on a lead, company or deal (lead_id / company_id / deal_id): body, optional title, kind (note by default; built-in call, meeting, email, coffee_chat, event, referral, or a workspace type from list_activity_types) and occurred_at.

list_activity_types

List activity types · read · scope crm:read · GET /api/v1/activity-types

The activity kinds log_activity accepts: built-in ones and the workspace's own.

Saved lead lists and segments

list_lead_lists

List lead lists · read · scope leads:read · GET /api/v1/lists

Saved lead lists: static lists (hand-picked members) and segments (saved lead filters: status, owner_id, company_id, q), with member counts.

get_lead_list

Get lead list · read · scope leads:read · GET /api/v1/lists/{list_id}

One lead list (list_id) with its kind, filters and member count.

list_lead_list_members

List members of a lead list · read · scope leads:read · GET /api/v1/lists/{list_id}/members

The leads in a list (list_id; a segment's are the leads matching its filters now), newest first; page with limit and cursor.

create_lead_list

Create lead list · write · scope leads:write · POST /api/v1/lists

Create a saved list (name, description): kind: static (then add leads) or kind: segment with filters (status list, owner_id, company_id, q).

update_lead_list

Update lead list · write · scope leads:write · PATCH /api/v1/lists/{list_id}

Rename a list or change its description, or a segment's filters (list_id).

add_leads_to_list

Add leads to a list · write · scope leads:write · POST /api/v1/lists/{list_id}/members

Add leads (lead_ids, up to 200) to a static list (list_id); leads already in it are skipped.

remove_leads_from_list

Remove leads from a list · write · scope leads:write · POST /api/v1/lists/{list_id}/members/remove

Take leads (lead_ids) out of a static list (list_id); the leads themselves stay.

enroll_lead_list

Enroll a list in a campaign · write · scope sequences:write · POST /api/v1/lists/{list_id}/enroll

Enroll every lead of a list (list_id) in a campaign (sequence_id). Leads already in it are skipped; consent, suppressions and limits are checked before anything is sent. Enrolling doesn't start a draft campaign.