# REST API

> Source: https://eesier.com/rest

The eesier REST API is a JSON API at `https://mcp.eesier.com` that exposes the same 202 tools as the MCP server. Every route takes a bearer token and returns JSON.

- **Base URL**: `https://mcp.eesier.com/rest/v1`
- **Authentication**: `Authorization: Bearer <token>`
- **Content type**: `application/json`
- **Get a token**: eesier console → Account → External Agents (MCP) → Generate Token. The same token works for MCP; revoking it kills both.

## First call

```bash
curl https://mcp.eesier.com/rest/v1/call/whoami \
  -H "Authorization: Bearer $EESIER_TOKEN"
```

## calling a tool

### Invoke a tool

```bash
curl -X POST https://mcp.eesier.com/rest/v1/tools/search_leads \
  -H "Authorization: Bearer $EESIER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "Interested", "page_size": 5}'
```

Everything else is a POST with a JSON object of named parameters.

### Discover every tool

```bash
curl https://mcp.eesier.com/rest/v1/tools \
  -H "Authorization: Bearer $EESIER_TOKEN"
```

The machine-readable version of this page, straight from the running server.

A tool with no parameters takes no body at all — an absent body, {} and null all mean "no arguments".

## the endpoints

| | | |
|---|---|---|
| `POST` | `/rest/v1/tools/{tool_name}` | Invoke a tool. The body is a JSON object of named parameters. |
| `GET` | `/rest/v1/call/{tool_name}` | Invoke a read-only tool from the query string. Any other tool returns 405. |
| `GET` | `/rest/v1/tools` | The full catalog: { version, server_version, tool_count, tools[] }. |
| `GET` | `/rest/v1/tools/{tool_name}` | One tool's schema — the same object the catalog lists. |

## responses

**The status says what happened** — A call that worked answers **200** with the tool's own JSON. A call that failed answers a real **4xx or 5xx** — and the body is still the tool's own JSON, so you get the machine-readable reason and a status your HTTP client can branch on without parsing anything.

- `200` — The tool ran and succeeded. Its JSON is the body.
- `400` — The request never reached the tool: malformed JSON, a non-object body, an unknown parameter, a missing required one, or a value that cannot be coerced.
- `401` — Missing, malformed, expired or revoked token.
- `403` — The tool exists but your plan does not include it. The body says what to activate.
- `404` — No tool by that name — the body suggests the nearest one — or the tool ran and the lead, campaign or website you asked for does not exist.
- `405` — Wrong verb — most often a GET invoke on a tool that is not read-only.
- `422` — The tool ran and refused the request on its own terms. The body says why.
- `500` — The tool threw and the failure is permanent for these arguments. Do not retry the identical call.
- `503` — The tool threw a transient platform or upstream error. Retry the same call in a few seconds.

Every 4xx and 5xx carries the same three fields, so one client codepath handles them all:

```json
{
  "error": "unknown parameter 'lead_ids' for tool 'get_lead'",
  "type": "UnknownParameter",
  "detail": "accepted parameters: lead_id"
}
```

- `UnknownTool` — That tool name does not exist. Check the suggestion in detail.
- `UnknownParameter` — You sent a parameter the tool does not accept — a typo is refused, never ignored.
- `MissingParameter` — A required parameter was absent.
- `ParameterTypeMismatch` — The value cannot be coerced to the parameter's type.
- `InvalidRequestBody` — The body parsed, but it is not a JSON object of named parameters.
- `NotReadOnly` — You tried to GET-invoke a tool that writes. Use POST.
- `JsonException` — The body is not valid JSON at all.

A missing or bad token returns 401 with a body that tells you what to do:

```json
{
  "error": "...",
  "how_to_fix": "...",
  "documentation": "https://mcp.eesier.com/SKILL.md"
}
```

## how values are read

Anything lossy is refused, never guessed.

- **string** — Text is taken verbatim. A JSON number or boolean arrives as its literal. Objects and arrays are refused — no parameter takes one.
- **integer** — A JSON number or its textual form. A fractional value like 3.7, or one out of range, is refused — never truncated, never wrapped.
- **number** — The decimal separator is '.', never ','. "1,5" fails loudly with a detail saying so, instead of silently becoming 15.
- **boolean** — Accepts true/false, "true"/"false", 1/0 and "1"/"0". "yes" is refused.
- **Unknown parameters are rejected** — Stricter than MCP on purpose: a silently-dropped typo would return a successful call with wrong-looking results. The 400 lists every accepted name.
- **null and omission differ** — Omit a parameter and the tool's own default applies. Explicit null is accepted only by a nullable parameter. A query string cannot express null — use POST when you need it.
- **Tool names are case-sensitive** — Dispatch is name-exact, matching MCP. get_lead works; GET_LEAD returns 404 with the right name in detail.
- **Dates are UTC ISO 8601** — Every timestamp comes back as 2026-01-31T14:05:00Z. Filters accept ISO dates. Call whoami for the account's timezone offset.
- **Lists page explicitly** — page starts at 0 and page_size defaults to 20, capped at 100. The total comes back alongside the rows.

## every endpoint

### Session

Identify the connected account and read its pending notifications. whoami is the first call of every session — it returns the profile, the plan and the account timezone.

#### `acknowledge_notification` (write)

Acknowledge a notification you have already surfaced to the user — it stops appearing in list_pending_notifications for you. This is an agent-side bookmark only: the platform's own delivery of the notification to the user is unaffected.

- `POST /rest/v1/tools/acknowledge_notification`

| Parameters | | |
|---|---|---|
| `notification_id` | integer, required | Notification ID (from list_pending_notifications) |

#### `list_notification_history` (read)

List the customer's past and pending system notifications (newest first, paginated) — including ones already processed by the platform or already acknowledged. Use list_pending_notifications for just the new, unseen ones.

- `POST /rest/v1/tools/list_notification_history`
- `GET /rest/v1/call/list_notification_history`

| Parameters | | |
|---|---|---|
| `page` | integer, optional, default `0` | Page number (0-based, default 0) |
| `page_size` | integer, optional, default `20` | Notifications per page (default 20, max 100) |

#### `list_pending_notifications` (read)

List all pending (unprocessed) system notifications queued for the customer. These are heads-up messages the platform wants the user to see — platform updates or action confirmations that haven't been surfaced yet. Surface them to the user; you cannot mark them as processed — they remain in the queue until the platform clears them internally. Sorted by oldest first. After surfacing one, call acknowledge_notification so it stops reappearing here; for past notifications use list_notification_history.

- `POST /rest/v1/tools/list_pending_notifications`
- `GET /rest/v1/call/list_pending_notifications`

Parameters: —

#### `whoami` (read)

Returns the authenticated customer's profile information including name, phone, email, language, timezone offset from UTC (in hours, may be null if not set), subscription plan, and prospecting eligibility.

- `POST /rest/v1/tools/whoami`
- `GET /rest/v1/call/whoami`

Parameters: —

### Leads

Search, read, register and update leads. Take a lead over from the agent, hand it back, stop it, or list everything waiting on a human right now.

#### `get_lead` (read)

Get a lead's full profile including contact info, company data, prospecting status, and conversation history. Email thread bodies are included inline (latest 50 per direction); WhatsApp and voice activity appear as counts — use get_lead_conversation for the full merged cross-channel timeline.

- `POST /rest/v1/tools/get_lead`
- `GET /rest/v1/call/get_lead`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |

#### `list_lead_emails` (read)

List the emails exchanged with a specific lead (outbound and inbound), oldest first. Paginated — outbound_total/inbound_total report the full thread size. Set include_bodies=false for a lightweight metadata-only view (dates, subjects, attachment names).

- `POST /rest/v1/tools/list_lead_emails`
- `GET /rest/v1/call/list_lead_emails`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |
| `page` | integer, optional, default `0` | Page number (0-based, default 0) |
| `page_size` | integer, optional, default `20` | Emails per direction per page (default 20, max 100) |
| `include_bodies` | boolean, optional, default `true` | Include full email bodies (default true); false returns metadata only |

#### `list_pending_review` (read)

List leads that have been flagged for human review by the prospecting agent.

- `POST /rest/v1/tools/list_pending_review`
- `GET /rest/v1/call/list_pending_review`

Parameters: —

#### `register_lead` (write)

Manually register a new lead so Blue Button can prospect it. A valid email is required for the lead to actually be contacted (phone alone only enables WhatsApp/voice). Deduplicates: if a lead with the same email or phone already exists, returns that lead's id instead of creating a duplicate. To bring in many leads at once use import_leads; for a lead referred by another lead use register_referral_lead.

- `POST /rest/v1/tools/register_lead`

| Parameters | | |
|---|---|---|
| `name` | string, required | Contact name |
| `email` | string, optional | Email address |
| `phone` | string, optional | Phone number |
| `company` | string, optional | Company name |
| `status` | string, optional | Initial status: Cold (default) or Confirmed |
| `campaign` | string, optional | Campaign name or numeric campaign_id to assign lead to |

#### `return_lead_to_pipeline` (write)

Return a lead to the autonomous prospecting pipeline with optional instructions for the next touch.

- `POST /rest/v1/tools/return_lead_to_pipeline`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |
| `instructions` | string, optional | Instructions for the agent's next touch |
| `next_touch_date` | string, optional | When to make the next touch (ISO date, default: now) |

#### `search_leads` (read)

Search leads by query, status, campaign, date range, or last prospecting message date. Supports sorting by date_created (default), last_prospecting_message, or status. Returns paginated results. Each result includes last_outbound_at (date of last outbound message sent to this lead) and last_inbound_at (date of last reply from this lead) so you can triage activity without opening the thread.

- `POST /rest/v1/tools/search_leads`
- `GET /rest/v1/call/search_leads`

| Parameters | | |
|---|---|---|
| `query` | string, optional | Search query (matches name, company name, email) |
| `status` | string, optional | Filter by status: Pending, Cold, Confirmed, Aware, NotInterested, Interested, Frozen, Closed, Unqualified, Rejected, Gatekeeper |
| `campaign` | string, optional | Filter by campaign name or numeric campaign_id |
| `created_after` | string, optional | Only leads created on or after this date (ISO format, e.g. 2026-01-01) |
| `created_before` | string, optional | Only leads created on or before this date (ISO format, e.g. 2026-03-31) |
| `last_prospecting_message_after` | string, optional | Only leads that received a prospecting message on or after this date (ISO format) |
| `sort_by` | string, optional | Sort order: date_created (default, newest first), last_prospecting_message (most recent activity first), status (by status then date). Unrecognized values default to date_created. |
| `page` | integer, optional, default `0` | Page number (0-based, default 0) |
| `page_size` | integer, optional, default `20` | Page size (default 20, max 100) |
| `has_linkedin` | boolean, optional | Filter by LinkedIn presence: true returns only leads that have a LinkedIn profile URL, false only leads without one. Omit for all leads. |

#### `send_message_to_lead` (write)

Send a direct email to a lead from the customer's Blue Button address. SIDE-EFFECT: this takes the lead over (removes it from the autonomous pipeline, same as take_over_lead) — the customer owns the conversation from then on. The email is queued for delivery, not sent instantly. If the customer only wants to steer the approach without taking over, use return_lead_to_pipeline with instructions instead. For WhatsApp use send_whatsapp_message_to_lead.

- `POST /rest/v1/tools/send_message_to_lead`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |
| `subject` | string, required | Email subject |
| `body` | string, required | Email body |

#### `stop_lead` (destructive)

Stop prospecting a lead — Blue Button finishes the lead and sends nothing further. Reversible: recover_lead_to_pipeline puts it back in the pipeline with re-engagement framing. Contrast: take_over_lead means the customer will personally handle the lead; stop_lead means nobody will. To record WHY (won/lost/gave up, deal value) use register_lead_outcome instead — it stops prospecting AND keeps the outcome history.

- `POST /rest/v1/tools/stop_lead`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |
| `reason` | string, optional | Reason for stopping |

#### `take_over_lead` (write)

Take over a lead — marks it as user-controlled, removing it from the autonomous prospecting pipeline (Blue Button stops contacting it; the customer handles it through their own channels). To hand the lead back to Blue Button later, use recover_lead_to_pipeline (gentle re-engagement). Contrast: stop_lead ends prospecting without implying the customer will handle it; send_message_to_lead also takes over as a side-effect; return_lead_to_pipeline is the post-human-review resume.

- `POST /rest/v1/tools/take_over_lead`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |

#### `update_lead` (write)

Update a lead's status, goal, or background. Pass only the fields you want to change. Note: setting a status here does NOT stop or pause prospecting — to remove the lead from the pipeline use stop_lead (finish permanently) or take_over_lead (customer handles it personally).

- `POST /rest/v1/tools/update_lead`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |
| `status` | string, optional | New status: Pending, Cold, Confirmed, Aware, NotInterested, Interested, Frozen, Closed, Unqualified, Rejected, Gatekeeper |
| `goal` | string, optional | Lead-specific outreach goal |
| `background` | string, optional | Background context about this lead |

### Lead operations

Act on a lead: send a WhatsApp message, import a list, reschedule the next touch, register a referral, or generate a presentation for one specific lead.

#### `create_lead_presentation` (write)

Generate a personalized strategic presentation (PDF) for a specific lead, based on the customer's business and the lead's context. Runs synchronously and can take a minute. Returns the PDF URL. If the lead already has a presentation, returns the existing one. Respects the customer/campaign 'generate custom presentations' toggle.

- `POST /rest/v1/tools/create_lead_presentation`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |

#### `import_leads` (write)

Import many leads at once. Provide EITHER an existing customer_file_id (an uploaded CSV/Excel/TXT file) OR inline rows (rows_json: a JSON array of objects with name, email, phone, company — email or phone required per row). The import is queued and processed in the background (deduped against existing leads); new leads enter prospecting automatically. For a single lead use register_lead.

- `POST /rest/v1/tools/import_leads`

| Parameters | | |
|---|---|---|
| `customer_file_id` | integer, optional | Id of an already-uploaded customer file (.csv, .xlsx, .xls, .txt) to import from |
| `rows_json` | string, optional | Inline leads as a JSON array, e.g. [{"name":"Ana","email":"ana@acme.com","phone":"+5511999999999","company":"Acme"}]. Max 500 rows per call. |
| `instructions` | string, optional | Special instructions for extraction (column mappings, filters) |
| `status` | string, optional | Initial status for imported leads (e.g. Cold, Confirmed) |
| `preferred_channel` | string, optional | First-contact channel: Email or WhatsApp (applied per lead only when it has that contact info) |
| `first_message_instructions` | string, optional | Instructions for the first prospecting message to imported leads |
| `prospecting_background` | string, optional | Background about the imported leads (e.g. 'Leads from TechConf 2026 workshop on AI') |
| `prospecting_goal` | string, optional | Outreach goal for the imported leads, overriding the customer-level goal |
| `campaign` | string, optional | Campaign name or numeric campaign_id to assign the imported leads to |

#### `register_referral_lead` (write)

Register a NEW lead that an existing lead referred ('talk to X'). Goes through the shared referral pipeline: dedupe, email verification, company-data copy when same_company, enrichment, and automatic entry into prospecting. Needs at least an email or a phone for the referred person. Requires an active paid plan.

- `POST /rest/v1/tools/register_referral_lead`

| Parameters | | |
|---|---|---|
| `referring_lead_id` | integer, required | ID of the existing lead who made the referral |
| `lead_name` | string, required | Name of the referred person |
| `lead_email` | string, optional | Email of the referred person |
| `lead_phone` | string, optional | Phone of the referred person |
| `same_company` | boolean, optional, default `false` | True when the referred person works at the SAME company as the referring lead (company data is copied over) |
| `status` | string, optional | Initial status (e.g. Cold, Confirmed) |
| `instructions_for_first_touch` | string, optional | Instructions for the first touch to the referred lead |

#### `reschedule_lead_touch` (write)

Update the next prospecting touch date and/or preferred channel for one or more actively-prospected leads, selected by explicit lead IDs and/or by the file they were imported from. Setting next_touch_date to now makes each lead be contacted as soon as possible. Leads the prospecting queue would not pick up (never started, finished, pending review, taken over, rejected, or frozen without a newer reply) are skipped and reported.

- `POST /rest/v1/tools/reschedule_lead_touch`

| Parameters | | |
|---|---|---|
| `lead_ids` | string, optional | Comma-separated lead IDs to update (optional if imported_from_file_id is provided) |
| `imported_from_file_id` | integer, optional | Update every actively-prospected lead imported from this customer file id |
| `next_touch_date` | string, optional | New next-touch date/time in UTC (ISO format). Pass the current UTC time to contact ASAP. Omit to keep each lead's schedule. |
| `preferred_channel` | string, optional | New preferred first-contact channel: Email or WhatsApp (applied only where the lead is reachable on that channel) |

#### `send_whatsapp_message_to_lead` (write)

Send a direct WhatsApp message to a lead on the customer's prospecting number. Behavior mirrors the in-app agent: if the lead is NOT taken over, the message is parked as next-touch instructions and delivered on the lead's next natural prospecting touch (the lead is NOT taken over). If the lead IS taken over and its 24h WhatsApp service window is open (the lead messaged within the last 24h), the message is sent now, verbatim; if the window is closed, the send is refused (WhatsApp policy) — use email via send_message_to_lead instead. Requires a live WhatsApp prospecting line (register_whatsapp_line).

- `POST /rest/v1/tools/send_whatsapp_message_to_lead`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |
| `message` | string, required | The message to deliver, written exactly as it should reach the lead |
| `attachment_url` | string, optional | Optional absolute https URL of a file to send as a WhatsApp media message after the text |

### Outcomes

Close the loop: record what happened with a lead, answer a question it asked, recover it into the pipeline, or read its lifecycle history.

#### `answer_lead_question` (write)

Save the customer's answer to a question a lead previously asked that the platform couldn't answer (price, delivery area, specs, process...). The answer is stored in the business FAQ so EVERY future lead gets it, and if the asking lead is still in the pipeline the answer is relayed on the next touch. Pass open_question_id when known; otherwise pass question_text.

- `POST /rest/v1/tools/answer_lead_question`

| Parameters | | |
|---|---|---|
| `answer_text` | string, required | The customer's answer, in their own words |
| `open_question_id` | integer, optional | ID of the open question being answered, when known |
| `question_text` | string, optional | The question text — required when no open_question_id is provided |

#### `list_lead_lifecycle_events` (read)

List the lifecycle/outcome history of a specific lead (outcome recorded, recovered, check-ins muted, questions answered, meeting outcomes...), newest first. The append-only audit trail behind register_lead_outcome and its siblings.

- `POST /rest/v1/tools/list_lead_lifecycle_events`
- `GET /rest/v1/call/list_lead_lifecycle_events`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |
| `limit` | integer, optional, default `50` | Max events to return (default 50, max 200) |

#### `mute_lead_check_ins` (write)

Stop the periodic 'how did it go with this lead?' check-in questions for a specific lead, when the customer asks not to be reminded about it anymore. Does NOT change the lead's status or pipeline state.

- `POST /rest/v1/tools/mute_lead_check_ins`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |
| `reason` | string, optional | Why the customer wants to stop hearing about this lead, in their own words |

#### `recover_lead_to_pipeline` (write)

Bring a lead the customer had taken over (or given up on) BACK into the autonomous prospecting pipeline with gentle re-engagement framing (the lead already knows the business). Use this — NOT return_lead_to_pipeline — when the customer PERSONALLY took over or stopped pursuing the lead and now wants Blue Button to resume it. Refuses unsubscribed leads and leads with a recorded won/lost outcome. The first re-engagement touch happens after a short delay.

- `POST /rest/v1/tools/recover_lead_to_pipeline`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |
| `owner_context` | string, optional | Context the customer gave for the recovery, in their words (e.g. 'he asked to talk after the holidays') |

#### `register_lead_outcome` (write)

Record the FINAL outcome of a lead as reported by the customer: 'won' (closed the sale), 'lost' (competitor, gave up, no budget), or 'gave_up' (the customer will no longer pursue this lead). Use for ANY update on how a lead's story ended — including casual positive announcements ('fechei com o X'). Also stops prospecting for the lead. Only pass reason/deal_value_brl when the customer volunteered them — NEVER ask for a deal value. Contrast: stop_lead ends prospecting without recording why; this keeps the outcome history.

- `POST /rest/v1/tools/register_lead_outcome`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |
| `outcome` | string, required | The outcome: 'won', 'lost', or 'gave_up' |
| `reason` | string, optional | The customer's own words about why/how it ended — only when volunteered |
| `deal_value_brl` | number, optional | Deal value in BRL — ONLY when the customer explicitly mentioned an amount |

### Meetings

List the meetings booked with leads, confirm or cancel them, and record who actually showed up.

#### `cancel_lead_meeting` (destructive)

Cancel a meeting on the customer's side and send the lead back into the prospecting pipeline so the executor communicates the cancellation on the next touch.

- `POST /rest/v1/tools/cancel_lead_meeting`

| Parameters | | |
|---|---|---|
| `meeting_id` | integer, required | Id of the meeting to cancel |
| `next_touch_date` | string, required | When the executor should re-engage the lead about the cancellation (ISO 8601 UTC, usually within a few hours) |
| `reason` | string, optional | Optional cancellation reason — appended to the meeting notes and included in the next-touch instructions |
| `additional_instructions` | string, optional | Optional extra next-touch instructions for the executor, written in the customer's language |

#### `confirm_lead_meeting` (write)

Confirm a meeting on the customer's side (call when the customer accepts a meeting the lead proposed). Stamps the customer's acceptance.

- `POST /rest/v1/tools/confirm_lead_meeting`

| Parameters | | |
|---|---|---|
| `meeting_id` | integer, required | Id of the meeting the customer is confirming |

#### `list_lead_meetings` (read)

List meetings between the customer and their leads. Optionally filter by a specific lead, include cancelled meetings, or include past meetings.

- `POST /rest/v1/tools/list_lead_meetings`
- `GET /rest/v1/call/list_lead_meetings`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, optional | Optional lead id to filter by |
| `include_cancelled` | boolean, optional, default `false` | Include cancelled meetings (default false) |
| `include_past` | boolean, optional, default `true` | Include past meetings from the last 30 days (default true). Set false for upcoming only. |

#### `update_lead_meeting_attendance` (write)

Record attendance for a meeting that already happened — whether the customer and/or the lead showed up, plus optional outcome notes. Pass at least one field.

- `POST /rest/v1/tools/update_lead_meeting_attendance`

| Parameters | | |
|---|---|---|
| `meeting_id` | integer, required | Id of the meeting to update |
| `has_customer_attended` | boolean, optional | Whether the customer attended |
| `has_lead_attended` | boolean, optional | Whether the lead attended |
| `notes` | string, optional | Optional outcome notes — appended to existing notes |

### Timing intelligence

Read the timing signals collected for a lead — when this kind of contact tends to answer.

#### `get_lead_timing_intelligence` (read)

Get a lead's timing intelligence: the best times to reach out (by day of week, in the lead's local time), when the lead historically responds, and their average response time. Built from this lead's history, falling back to their sector, this customer, then platform-wide data (the source field says which). Use it to time send_message_to_lead / return_lead_to_pipeline touches.

- `POST /rest/v1/tools/get_lead_timing_intelligence`
- `GET /rest/v1/call/get_lead_timing_intelligence`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |

### Conversations

Read what was actually said. Full cross-channel timeline for one lead, the WhatsApp thread on its own, or a meaning-based search across every lead conversation at once.

#### `get_lead_conversation` (read)

Get a lead's full cross-channel conversation timeline — email, WhatsApp, and voice calls — merged chronologically, each item tagged with its channel and direction. Paginated. This is the one tool that shows the WHOLE conversation as the lead experienced it; for a single channel use list_lead_emails or list_lead_whatsapp_messages.

- `POST /rest/v1/tools/get_lead_conversation`
- `GET /rest/v1/call/get_lead_conversation`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |
| `page` | integer, optional, default `0` | Page number (0-based, default 0) |
| `page_size` | integer, optional, default `30` | Items per page (default 30, max 100) |
| `order` | string, optional, default `newest_first` | Ordering: newest_first (default) or oldest_first |
| `include_transcripts` | boolean, optional, default `false` | Include full voice-call transcripts (default false — only the outcome summary) |

#### `list_lead_whatsapp_messages` (read)

List the WhatsApp messages exchanged with a specific lead (outbound and inbound), oldest first. Paginated — outbound_total/inbound_total report the full thread size. Set include_bodies=false for a lightweight metadata-only view. For the lead's emails use list_lead_emails; for the merged email+WhatsApp+voice timeline use get_lead_conversation.

- `POST /rest/v1/tools/list_lead_whatsapp_messages`
- `GET /rest/v1/call/list_lead_whatsapp_messages`

| Parameters | | |
|---|---|---|
| `lead_id` | integer, required | Lead ID |
| `page` | integer, optional, default `0` | Page number (0-based, default 0) |
| `page_size` | integer, optional, default `20` | Messages per direction per page (default 20, max 100) |
| `include_bodies` | boolean, optional, default `true` | Include full message bodies (default true); false returns metadata only |

#### `search_lead_conversations` (read)

Semantic search ACROSS ALL the customer's LEAD conversations — lead emails and lead WhatsApp messages — by meaning, not keywords (e.g. 'leads who asked about pricing', 'objections about contract length'). Returns snippets with lead_id; fetch full threads via get_lead_conversation / list_lead_emails / list_lead_whatsapp_messages. Optionally scope to one lead or one channel. NOT for the customer's own chat with their Blue Button agent — that is search_my_agent_conversation.

- `POST /rest/v1/tools/search_lead_conversations`
- `GET /rest/v1/call/search_lead_conversations`

| Parameters | | |
|---|---|---|
| `query` | string, required | What to search for, phrased by meaning (any language) |
| `lead_id` | integer, optional | Restrict to one lead's conversation (optional) |
| `channel` | string, optional | Restrict channel: email, whatsapp, email_inbound, email_outbound, whatsapp_inbound, whatsapp_outbound (optional; default = all) |
| `top_k` | integer, optional, default `10` | Max results (default 10, max 25) |
| `min_score` | number, optional | Minimum similarity score 0..1 (optional) |

#### `search_my_agent_conversation` (read)

Semantic search over the customer's OWN past conversation with their Blue Button agent (the WhatsApp assistant they talk to) — use it to recall what the customer previously discussed, decided, or asked for. NOT for lead conversations — that is search_lead_conversations.

- `POST /rest/v1/tools/search_my_agent_conversation`
- `GET /rest/v1/call/search_my_agent_conversation`

| Parameters | | |
|---|---|---|
| `query` | string, required | What to search for, phrased by meaning (any language) |
| `top_k` | integer, optional, default `5` | Max results (default 5, max 10) |

### Campaigns

Run separate prospecting tracks for different products or markets: create, pause, resume, rename, archive, compare results, and move leads between them.

#### `archive_campaign` (destructive)

Archives a campaign permanently. Every lead in it has its campaign link cleared and goes back to default prospecting, and the campaign stops appearing in campaign lists. Use pause_campaign instead for a temporary stop.

- `POST /rest/v1/tools/archive_campaign`

| Parameters | | |
|---|---|---|
| `name` | string, required | Campaign name or numeric campaign_id |

#### `compare_campaigns` (read)

Compare two campaigns side-by-side: configuration and lead stats.

- `POST /rest/v1/tools/compare_campaigns`
- `GET /rest/v1/call/compare_campaigns`

| Parameters | | |
|---|---|---|
| `name_a` | string, required | First campaign name |
| `name_b` | string, required | Second campaign name |

#### `create_campaign` (write)

Creates a new prospecting campaign. Name and business_name are required. Each campaign is ISOLATED — it does NOT inherit any field from the customer-level defaults, so populate every field that matters at creation time.

- `POST /rest/v1/tools/create_campaign`

| Parameters | | |
|---|---|---|
| `name` | string, required | Campaign name (unique per customer) |
| `business_name` | string, required | Business name for this campaign |
| `business_description` | string, optional | Business description for this campaign — the product/service it represents. REQUIRED when the campaign represents a different product than the customer's main business, otherwise prospecting copy will have no product context. |
| `business_website` | string, optional | Business website URL for this campaign |
| `icp` | string, optional | Ideal customer profile |
| `cnae_filter` | string, optional | Comma-separated CNAE codes to include |
| `cnae_exclusion_filter` | string, optional | Comma-separated CNAE codes to exclude |
| `instructions` | string, optional | Prospecting instructions |
| `email_instructions` | string, optional | Email-channel instructions overlay — extra guidance applied ONLY when reaching a lead by email for THIS campaign, layered on top of the campaign's general instructions (raw replace of the email overlay). |
| `whatsapp_instructions` | string, optional | WhatsApp-channel instructions overlay — extra guidance applied ONLY when reaching a lead on WhatsApp for THIS campaign, layered on top of the campaign's general instructions (raw replace of the WhatsApp overlay). |
| `voice_instructions` | string, optional | Voice-channel instructions overlay — extra guidance applied ONLY on outbound calls for THIS campaign, layered on top of the campaign's general instructions (raw replace of the voice overlay). |
| `goal` | string, optional | Outreach goal |
| `lead_qualification_instructions` | string, optional | Lead qualification instructions — rules for HOW to evaluate leads against the ICP (hard requirements vs. flexible preferences, override conditions, leniency rules, disqualification thresholds) |
| `human_review_criteria` | string, optional | Human review criteria — when to flag a lead for manual review instead of auto-advancing |
| `email_display_name` | string, optional | Email display name override for this campaign (e.g. 'Carlos from PrimeAssist'). Leave blank to use the customer-level display name. |
| `uf_filter` | string, optional | Comma-separated Brazilian state codes (e.g. 'SP,RJ,MG') |
| `city_filter` | string, optional | Comma-separated city names |
| `country_filter` | string, optional | ISO country codes |
| `min_employee_count` | integer, optional | Minimum employee count |
| `max_employee_count` | integer, optional | Maximum employee count |
| `min_annual_revenue` | number, optional | Minimum annual revenue |
| `max_annual_revenue` | number, optional | Maximum annual revenue |
| `company_size_filter` | string, optional | Comma-separated company sizes: Micro,Small,Medium,Large |
| `company_type_filter` | string, optional | Comma-separated company types to include in lead searches: Private, Individual, Government, StateOwned, NonProfit. Empty = inherit the customer's company type filter (customer default = Private only — MEI / individual entrepreneurs, government, state-owned and non-profit entities excluded). |
| `lead_generation_active` | boolean, optional | Whether to auto-generate NEW leads for this track. Defaults to true. Set to false ONLY when the campaign should ONLY work on a list the user imports themselves and never receive auto-generated leads. Existing leads still get prospected — only new lead acquisition is paused when false. |

#### `get_campaign` (read)

Returns full configuration and lead stats for a specific campaign. Accepts the campaign name or its numeric campaign_id (as returned by list_campaigns, search_leads, get_lead).

- `POST /rest/v1/tools/get_campaign`
- `GET /rest/v1/call/get_campaign`

| Parameters | | |
|---|---|---|
| `name` | string, required | Campaign name or numeric campaign_id |

#### `list_campaigns` (read)

Lists all prospecting campaigns for the customer with their lead stats (total, interested, confirmed, cold, aware, frozen, not interested, taken over, pending review) and email metrics (emails sent, replies received, reply rate).

- `POST /rest/v1/tools/list_campaigns`
- `GET /rest/v1/call/list_campaigns`

Parameters: —

#### `move_leads_to_campaign` (write)

Move leads from one campaign to another, or remove them from their campaign and return them to default (no-campaign) prospecting. Pass the target campaign name, or 'default' to remove the leads from any campaign. Optionally filter by lead status.

- `POST /rest/v1/tools/move_leads_to_campaign`

| Parameters | | |
|---|---|---|
| `target_campaign` | string, required | Target campaign name or numeric campaign_id, or 'default' (or 'none') to remove the leads from their campaign and return them to default prospecting |
| `lead_ids` | string, required | Comma-separated lead IDs to move |
| `status_filter` | string, optional | Only move leads with this status (optional) |

#### `pause_campaign` (write)

Pauses a campaign. Leads in this campaign will not be processed until resumed.

- `POST /rest/v1/tools/pause_campaign`

| Parameters | | |
|---|---|---|
| `name` | string, required | Campaign name or numeric campaign_id |

#### `rename_campaign` (write)

Renames a campaign.

- `POST /rest/v1/tools/rename_campaign`

| Parameters | | |
|---|---|---|
| `old_name` | string, required | Current campaign name |
| `new_name` | string, required | New campaign name |

#### `resume_campaign` (write)

Resumes a paused campaign.

- `POST /rest/v1/tools/resume_campaign`

| Parameters | | |
|---|---|---|
| `name` | string, required | Campaign name or numeric campaign_id |

#### `set_campaign_lead_generation_active` (write)

Toggles whether the system AUTO-GENERATES new leads for a campaign. true = generate new leads (default). false = stop generating new leads — only work the existing list. INDEPENDENT from pause/resume: a campaign with lead_generation_active=false but is_active=true still prospects its existing leads, just no new lead acquisition. Use this when the user wants a campaign to work ONLY on a list they imported themselves.

- `POST /rest/v1/tools/set_campaign_lead_generation_active`

| Parameters | | |
|---|---|---|
| `name` | string, required | Campaign name or numeric campaign_id |
| `active` | boolean, required | true to keep generating new leads, false to stop generating new leads (existing leads still get prospected) |

#### `update_campaign` (write)

Updates an existing campaign's configuration. Pass only the fields you want to change. For numeric filters (employee count, revenue), set to -1 to clear.

- `POST /rest/v1/tools/update_campaign`

| Parameters | | |
|---|---|---|
| `name` | string, required | Current campaign name |
| `business_name` | string, optional | New business name |
| `business_description` | string, optional | Business description |
| `business_website` | string, optional | Business website |
| `icp` | string, optional | Ideal customer profile |
| `cnae_filter` | string, optional | CNAE inclusion filter |
| `cnae_exclusion_filter` | string, optional | CNAE exclusion filter |
| `uf_filter` | string, optional | Comma-separated Brazilian state codes (e.g. 'SP,RJ,MG') |
| `city_filter` | string, optional | Comma-separated city names |
| `country_filter` | string, optional | Country filter |
| `instructions` | string, optional | Prospecting instructions |
| `email_instructions` | string, optional | Email-channel instructions overlay — extra guidance applied ONLY when reaching a lead by email for THIS campaign, layered on top of the campaign's general instructions (raw replace of the email overlay). |
| `whatsapp_instructions` | string, optional | WhatsApp-channel instructions overlay — extra guidance applied ONLY when reaching a lead on WhatsApp for THIS campaign, layered on top of the campaign's general instructions (raw replace of the WhatsApp overlay). |
| `voice_instructions` | string, optional | Voice-channel instructions overlay — extra guidance applied ONLY on outbound calls for THIS campaign, layered on top of the campaign's general instructions (raw replace of the voice overlay). |
| `goal` | string, optional | Outreach goal |
| `strategy` | string, optional | Strategy |
| `human_review_criteria` | string, optional | Human review criteria |
| `lead_qualification_instructions` | string, optional | Lead qualification instructions — rules for HOW to evaluate leads against the ICP (hard requirements vs. flexible preferences, override conditions, leniency rules, disqualification thresholds) |
| `email_display_name` | string, optional | Email display name |
| `min_employee_count` | integer, optional | Minimum employee count (-1 to clear) |
| `max_employee_count` | integer, optional | Maximum employee count (-1 to clear) |
| `min_annual_revenue` | number, optional | Minimum annual revenue (-1 to clear) |
| `max_annual_revenue` | number, optional | Maximum annual revenue (-1 to clear) |
| `company_size_filter` | string, optional | Comma-separated company sizes: Micro,Small,Medium,Large (empty to clear) |
| `company_type_filter` | string, optional | Comma-separated company types to include in lead searches: Private, Individual, Government, StateOwned, NonProfit. Empty string clears the campaign override and inherits the customer's company type filter (customer default = Private only — MEI / individual entrepreneurs, government, state-owned and non-profit entities excluded). |
| `lead_generation_active` | boolean, optional | Whether to auto-generate NEW leads for this track. true = generate new leads (default for new campaigns). false = stop generating new leads, only work the existing list. Independent from pause/resume — when false the campaign keeps prospecting its existing leads, just doesn't acquire new ones. |
| `is_active` | boolean, optional | Whether this campaign is running at all. false pauses the whole track (same as pause_campaign), true resumes it. |
| `voice_calling_active` | boolean, optional | Per-track outbound voice calling. true calls this track's leads, false never calls them, omit to keep the current setting. Cleared to inherit the customer-level toggle via clear_voice_calling_active. |
| `generate_custom_presentations` | boolean, optional | Whether to generate a per-lead custom presentation for this track (true/false) |
| `notify_on_interested` | boolean, optional | Alert when a lead of this track shows interest (true/false) |
| `notify_on_confirmed` | boolean, optional | Alert when a lead of this track is confirmed (true/false) |
| `min_founding_date` | string, optional | Earliest company founding date to include, as 'yyyy-MM-dd' (empty to clear) |
| `max_founding_date` | string, optional | Latest company founding date to include, as 'yyyy-MM-dd' (empty to clear) |

### Prospecting settings

The master switch plus everything that shapes who gets contacted and how: targeting, rules and preferences.

#### `get_prospecting_config` (read)

Returns all prospecting configuration: filters (CNAE, location), instructions, goal, strategy, human review criteria, lead qualification instructions, notification settings, mode, and activation status.

- `POST /rest/v1/tools/get_prospecting_config`
- `GET /rest/v1/call/get_prospecting_config`

Parameters: —

#### `set_allow_template_whatsapp_messages` (write)

Allows or blocks agent-initiated WhatsApp template messages to leads. When blocked the agent may only reply to leads who wrote first, inside WhatsApp's 24-hour window, and never opens a conversation by template. Free-form replies are unaffected.

- `POST /rest/v1/tools/set_allow_template_whatsapp_messages`

| Parameters | | |
|---|---|---|
| `allowed` | boolean, required | true to allow agent-initiated template messages, false to reply-only |

#### `set_prospecting_active` (write)

Activates or deactivates autonomous prospecting. Returns the new status and eligibility information.

- `POST /rest/v1/tools/set_prospecting_active`

| Parameters | | |
|---|---|---|
| `active` | boolean, required | true to activate, false to deactivate |

#### `set_prospecting_preferences` (write)

Updates prospecting preferences: mode (Active/Passive), custom presentations, and notification settings. Pass only the fields you want to change.

- `POST /rest/v1/tools/set_prospecting_preferences`

| Parameters | | |
|---|---|---|
| `mode` | string, optional | Prospecting mode: 'Active' (searching for leads) or 'Passive' (paused until review) |
| `generate_presentations` | boolean, optional | Whether to generate custom presentations per lead (true/false) |
| `notification_email` | string, optional | Email address to receive prospecting notifications |
| `notify_on_interested` | boolean, optional | Notify (in-app/WhatsApp) when leads show interest (true/false) |
| `notify_on_confirmed` | boolean, optional | Notify (in-app/WhatsApp) when leads are confirmed (true/false) |
| `notify_on_interested_via_email` | boolean, optional | Send the branded EMAIL when leads show interest (true/false) — independent of the in-app/WhatsApp alert |
| `notify_on_confirmed_via_email` | boolean, optional | Send the branded EMAIL when leads are confirmed (true/false) — independent of the in-app/WhatsApp alert |
| `notify_on_first_whatsapp_message` | boolean, optional | Notify (one-time heads-up) when a lead sends their first WhatsApp message (true/false) |
| `cc_on_interested_lead_emails` | boolean, optional | Copy the customer on the interested-lead emails sent to the notification addresses (true/false) |

#### `set_prospecting_rules` (write)

Updates prospecting rules: instructions for the agent, outreach goal, strategy, human review criteria, and lead qualification instructions. Pass only the fields you want to change.

- `POST /rest/v1/tools/set_prospecting_rules`

| Parameters | | |
|---|---|---|
| `instructions` | string, optional | Instructions for how the agent should prospect (raw replace) |
| `goal` | string, optional | Desired outreach goal (e.g. 'schedule a demo', 'book a meeting') |
| `strategy` | string, optional | Prospecting strategy document |
| `human_review_criteria` | string, optional | Criteria for when to escalate leads to human review |
| `lead_qualification_instructions` | string, optional | Rules for HOW to evaluate leads against the ICP — which characteristics are hard requirements vs. flexible preferences, override conditions, leniency rules, disqualification thresholds. Distinct from the ICP itself (who to target). |
| `email_instructions` | string, optional | Email-channel instructions overlay — extra guidance applied ONLY when reaching a lead by email, layered on top of the general instructions (raw replace of the email overlay). |
| `whatsapp_instructions` | string, optional | WhatsApp-channel instructions overlay — extra guidance applied ONLY when reaching a lead on WhatsApp, layered on top of the general instructions (raw replace of the WhatsApp overlay). |
| `voice_instructions` | string, optional | Voice-channel instructions overlay — extra guidance applied ONLY on outbound calls, layered on top of the general instructions (raw replace of the voice overlay). |
| `email_signature` | string, optional | Exact signature block appended verbatim to every prospecting email. When set, the copywriter writes no signature of its own. Pass an empty string to clear it and go back to the default name-only signature. |

#### `set_targeting` (write)

Updates prospecting targeting filters. Pass only the fields you want to change. Comma-separated values for multi-value fields. For numeric filters (employee count, revenue), set to -1 to clear.

- `POST /rest/v1/tools/set_targeting`

| Parameters | | |
|---|---|---|
| `cnae_filter` | string, optional | Comma-separated CNAE codes to include (e.g. '6201,6202,6311') |
| `cnae_exclusion_filter` | string, optional | Comma-separated CNAE codes to exclude |
| `uf_filter` | string, optional | Comma-separated Brazilian state codes (e.g. 'SP,RJ,MG') |
| `city_filter` | string, optional | Comma-separated city names |
| `country_filter` | string, optional | Comma-separated ISO country codes (e.g. 'BR,US') |
| `min_employee_count` | integer, optional | Minimum employee count (-1 to clear) |
| `max_employee_count` | integer, optional | Maximum employee count (-1 to clear) |
| `min_annual_revenue` | number, optional | Minimum annual revenue (-1 to clear) |
| `max_annual_revenue` | number, optional | Maximum annual revenue (-1 to clear) |
| `company_size_filter` | string, optional | Comma-separated company sizes: Micro,Small,Medium,Large (empty to clear) |
| `company_type_filter` | string, optional | Comma-separated company types to include in lead searches: Private, Individual, Government, StateOwned, NonProfit. Default (empty) = Private only — MEI / individual entrepreneurs, government, state-owned and non-profit entities are excluded. |
| `min_founding_date` | string, optional | Earliest company founding date to include, as 'yyyy-MM-dd' (empty to clear) |
| `max_founding_date` | string, optional | Latest company founding date to include, as 'yyyy-MM-dd' (empty to clear) |

### Prospecting files

The catalog of files the agent may send to a lead — presentations, price tables, guides — scoped to a campaign or to the whole account.

#### `list_prospecting_files` (read)

List the prospecting files catalog — the materials the prospecting agent can offer and send to leads, with each file's title, description, url and campaign scope.

- `POST /rest/v1/tools/list_prospecting_files`
- `GET /rest/v1/call/list_prospecting_files`

Parameters: —

#### `register_prospecting_file` (write)

Register a file in the prospecting files catalog — the materials the prospecting agent can offer and SEND TO LEADS during outreach (price table, institutional presentation, onboarding guide), via email attachments and WhatsApp documents. Provide either customer_file_id (an already-uploaded customer file — preferred) or a direct url. If no description is given, one is auto-generated from the file's content so the agent knows when to send it. NOT for business knowledge the agent answers questions from (register_business_file) and NOT the per-lead AI-generated custom guide.

- `POST /rest/v1/tools/register_prospecting_file`

| Parameters | | |
|---|---|---|
| `title` | string, required | Short lead-facing title, e.g. 'Tabela de precos' |
| `description` | string, optional | What the file contains and when to send it to a lead (1-3 sentences). Leave empty to auto-generate from the file's content. |
| `customer_file_id` | integer, optional | Id of an existing customer file to register (preferred over a raw url) |
| `url` | string, optional | Direct public URL of the file (alternative to customer_file_id) |
| `campaign` | string, optional | Optional campaign name to make the file sendable ONLY to that campaign's leads. Leave empty for a customer-wide file sendable to every lead. |
| `sort_order` | integer, optional, default `0` | Catalog display/prompt order (lower first, default 0) |

#### `remove_prospecting_file` (destructive)

Remove a file from the prospecting files catalog so the prospecting agent stops offering and sending it to leads. Find the id with list_prospecting_files.

- `POST /rest/v1/tools/remove_prospecting_file`

| Parameters | | |
|---|---|---|
| `prospecting_file_id` | integer, required | Id of the prospecting file to remove |

#### `update_prospecting_file` (write)

Update a prospecting file's title, description, campaign scope or display order. Find the id with list_prospecting_files. To change the file itself, remove the entry and register a new one.

- `POST /rest/v1/tools/update_prospecting_file`

| Parameters | | |
|---|---|---|
| `prospecting_file_id` | integer, required | Id of the prospecting file to update |
| `title` | string, optional | New lead-facing title |
| `description` | string, optional | New description of what the file contains and when to send it |
| `campaign` | string, optional | Campaign name to scope the file to, or 'all' to make it customer-wide |
| `sort_order` | integer, optional | New catalog display/prompt order (lower first) |

### Reports

The numbers: headline prospecting report, funnel by industry and by state, performance trends, message performance, volume estimates, and a narrative catch-up of what changed.

#### `estimate_lead_volume` (read)

Returns a benchmark of what a typical PAID Blue Button customer (and paid customers with a similar ICP) produces in the last 30 days: new leads found, confirmed responses (real conversations), interested (hot) leads, and messages sent — each shown as a range from median (typical customer) to top (more active ones) per week and per month. Free-trial-only users are excluded. The tool picks the most relevant benchmark automatically — Similar (CNAE-overlapping paid customers) when available, Global (all paid customers) otherwise.

- `POST /rest/v1/tools/estimate_lead_volume`
- `GET /rest/v1/call/estimate_lead_volume`

Parameters: —

#### `get_funnel_by_industry` (read)

Get a funnel breakdown by industry. For Brazilian customers, groups by CNAE division. For international customers, groups by the CompanyIndustry field from Apollo/Lusha data. Optionally filter by campaign.

- `POST /rest/v1/tools/get_funnel_by_industry`
- `GET /rest/v1/call/get_funnel_by_industry`

| Parameters | | |
|---|---|---|
| `campaign` | string, optional | Filter by campaign name or numeric campaign_id (optional, omit for global funnel) |

#### `get_funnel_timeline` (read)

Count of leads ENTERING each funnel stage per time bucket (day or week). Stages tracked: cold (DateProspectingStarted), confirmed (DateConfirmedProspectingQualification), interested (DateConfirmedInterest), closed (DateStatusChanged while current Status=Closed — APPROXIMATION: a lead that was Closed and later moved to another status will not be counted, because the platform does not store status history). Aware is not exposed — the platform does not reliably track entry into that stage. Missing buckets gap-filled with zeros, newest-first. Optionally filter by campaign.

- `POST /rest/v1/tools/get_funnel_timeline`
- `GET /rest/v1/call/get_funnel_timeline`

| Parameters | | |
|---|---|---|
| `days` | integer, optional, default `30` | Number of days to look back (default 30, max 365) |
| `bucket` | string, optional, default `day` | Bucket size: 'day' (default) or 'week' (Monday-aligned) |
| `campaign` | string, optional | Filter by campaign name or numeric campaign_id (optional, omit for global timeline) |

#### `get_message_performance` (read)

Reply rate broken down by campaign and/or message type over a time window. Returns total sent, replied (distinct outbound emails with at least one reply), reply_rate_pct, plus a breakdown. Breakdown shape depends on group_by: 'campaign' returns one row per campaign (message types collapsed); 'type' returns one row per message type (campaigns collapsed); 'both' (default) returns one row per campaign×type combination (a matrix — NOT two separate lists — so expect up to N_campaigns × N_types rows). Message types: first_contact (AutonomousFirstTouch), follow_up (AutonomousFollowUp), response (AutonomousResponse to inbound), direct (DirectMessage sent on user's behalf), user_written (UserWrittenMessage sent manually by user). Defaults to 30 days.

- `POST /rest/v1/tools/get_message_performance`
- `GET /rest/v1/call/get_message_performance`

| Parameters | | |
|---|---|---|
| `days` | integer, optional, default `30` | Number of days to look back (default 30, max 365) |
| `campaign` | string, optional | Filter by campaign name or numeric campaign_id (optional, omit for all campaigns) |
| `group_by` | string, optional, default `both` | How to group the breakdown: 'campaign', 'type', or 'both' (default) |

#### `get_metrics_by_state_and_industry` (read)

Breaks down every prospecting metric by Brazilian STATE and by INDUSTRY (CNAE description) over a time window, so you can compare which states/industries are performing best. For each dimension it returns the top groups by lead volume — each with new_leads, emails_sent, responses, whatsapp_sent, whatsapp_responses, conscientizados, interested (became interested in the window), confirmed_aware_interested_or_takenover, referrals, and meeting counts (invitations made/received, booked, made) — plus the top-performing group per metric category. Leads with no state/CNAE fall into 'Não informado' and are excluded from the top-performer picks. interested is counted by DateConfirmedInterest (the moment the lead converted). Optionally filter by campaign.

- `POST /rest/v1/tools/get_metrics_by_state_and_industry`
- `GET /rest/v1/call/get_metrics_by_state_and_industry`

| Parameters | | |
|---|---|---|
| `days` | integer, optional, default `30` | Number of days to look back (default 30, max 365) |
| `campaign` | string, optional | Filter by campaign name or numeric campaign_id (optional, omit for whole account) |

#### `get_performance_trends` (read)

Get prospecting performance trends per day over the specified window. All metrics are daily FLOW counts (events that happened on that day), not cumulative stocks. Each row has: leads_generated (leads created that day), emails_sent (outbound prospecting emails sent that day), replies_received (inbound replies to outbound emails received that day), confirmed (leads whose status became Confirmed for the first time on that day, i.e. DateConfirmedProspectingQualification falls on the day), interested (leads whose status became Interested for the first time on that day, i.e. DateConfirmedInterest falls on the day — this is the per-day entry count, NOT the total number of leads currently with Status=Interested), whatsapp_sent (prospecting WhatsApp messages sent that day, by DateSent), whatsapp_replies_received (WhatsApp replies from leads that day, by the lead's send timestamp). Missing days are gap-filled with zeros. Optionally filter by campaign.

- `POST /rest/v1/tools/get_performance_trends`
- `GET /rest/v1/call/get_performance_trends`

| Parameters | | |
|---|---|---|
| `days` | integer, optional, default `30` | Number of days to look back (default 30, max 365) |
| `campaign` | string, optional | Filter by campaign name or numeric campaign_id (optional, omit for global trends) |

#### `get_prospecting_report` (read)

Get an overall prospecting report: total leads, leads by status, emails sent, response rate, and pipeline summary. Also returns WhatsApp activity: whatsapp_sent (prospecting WhatsApp messages sent), whatsapp_responses (WhatsApp replies received, counted separately from email responses), and leads_talked_to_on_whatsapp (distinct leads with any WhatsApp message in either direction). Optionally filter by campaign.

- `POST /rest/v1/tools/get_prospecting_report`
- `GET /rest/v1/call/get_prospecting_report`

| Parameters | | |
|---|---|---|
| `campaign` | string, optional | Filter by campaign name or numeric campaign_id (optional, omit for global report) |

#### `get_whatsapp_message_performance` (read)

WhatsApp reply performance broken down by campaign and/or message type over a time window. NOTE: unlike get_message_performance (email), WhatsApp reply rate is reported at the LEAD level — WhatsApp inbound has no per-message link to a specific outbound, so 'replied' cannot be attributed per message. Returns total sent (message count), leads_messaged (distinct leads contacted), leads_replied (distinct leads who sent at least one inbound on/after their first outbound of that type in the window), lead_reply_rate_pct (leads_replied / leads_messaged), plus a breakdown. group_by: 'campaign' (one row per campaign), 'type' (one row per message type), 'both' (default, campaign×type matrix). Message types: first_contact (AutonomousFirstTouch), follow_up (AutonomousFollowUp), response (AutonomousResponse), direct (DirectMessage), user_written (UserWrittenMessage). Defaults to 30 days.

- `POST /rest/v1/tools/get_whatsapp_message_performance`
- `GET /rest/v1/call/get_whatsapp_message_performance`

| Parameters | | |
|---|---|---|
| `days` | integer, optional, default `30` | Number of days to look back (default 30, max 365) |
| `campaign` | string, optional | Filter by campaign name or numeric campaign_id (optional, omit for all campaigns) |
| `group_by` | string, optional, default `both` | How to group the breakdown: 'campaign', 'type', or 'both' (default) |

#### `list_prospecting_optimizations` (read)

Lists the autonomous prospecting optimization history in reverse-chronological order (newest first). Paginated. Each entry shows when the prospecting reviewer agent ran and what targeting/configuration changes it made and why. Optionally filter by campaign.

- `POST /rest/v1/tools/list_prospecting_optimizations`
- `GET /rest/v1/call/list_prospecting_optimizations`

| Parameters | | |
|---|---|---|
| `campaign` | string, optional | Filter by campaign name or numeric campaign_id (optional, omit for all optimizations) |
| `page` | integer, optional, default `0` | Page number (0-based, default 0) |
| `page_size` | integer, optional, default `20` | Page size (default 20, max 100) |

#### `what_changed_since` (read)

Full digest of what happened in the prospecting operation since a given date — built for the 'I've been away for months, what happened?' case. Blocks: (1) activity_summary — the engine's raw work in the window: new_leads, emails_sent, email_replies, whatsapp_sent, whatsapp_replies; (2) funnel_progress — leads that reached each stage in the window: reached_confirmed, became_interested; (3) new_interested_leads — the interested leads themselves (up to 100, plus total_count); (4) outcomes — deals closed in the window: won_count, lost_count, gave_up_count, total_deal_value_brl, and won_items; (5) meetings — booked, cancelled, held, no_show counts in the window plus items; (6) pending_human_review — the CURRENT pile of leads waiting on the owner (a live snapshot, NOT limited to the window): total_count plus items; (7) support_answered — support requests the team answered in the window (message + answer); (8) campaign_performance_changes — campaigns whose reply rate shifted by at least 3 percentage points (30-day window ending on since_date vs since_date→now, skipping windows with fewer than 50 sent); (9) optimizer_adjustments — prospecting-optimizer changes persisted since that date (capped at 500 items; total_count/returned_count/truncated report the true total). All windowed counts cover since_date→now; timestamps are UTC.

- `POST /rest/v1/tools/what_changed_since`
- `GET /rest/v1/call/what_changed_since`

| Parameters | | |
|---|---|---|
| `since_date` | string, required | ISO date in YYYY-MM-DD format (e.g. 2026-01-15) |

### Voice calls

Place a goal-driven phone call to a lead, read the calls already placed, and switch voice calling on or off per account or per campaign.

#### `get_campaign_voice_calling_active` (read)

Read a campaign's voice-calling toggle. A null value means the campaign inherits the customer-level toggle.

- `POST /rest/v1/tools/get_campaign_voice_calling_active`
- `GET /rest/v1/call/get_campaign_voice_calling_active`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | Name of the campaign |

#### `get_voice_call` (read)

Get the status and outcome of a goal-driven phone call placed with place_goal_driven_call: lifecycle status, whether a person picked up, whether the goal was achieved, the outcome summary, and the full transcript.

- `POST /rest/v1/tools/get_voice_call`
- `GET /rest/v1/call/get_voice_call`

| Parameters | | |
|---|---|---|
| `voice_call_request_id` | integer, required | The voice_call_request_id returned by place_goal_driven_call |

#### `get_voice_calling_active` (read)

Read whether autonomous outbound voice calling to leads is active at the customer level.

- `POST /rest/v1/tools/get_voice_calling_active`
- `GET /rest/v1/call/get_voice_calling_active`

Parameters: —

#### `list_voice_calls` (read)

List the customer's goal-driven phone calls (newest first) with status and outcome summary. Use get_voice_call for the full transcript of one call.

- `POST /rest/v1/tools/list_voice_calls`
- `GET /rest/v1/call/list_voice_calls`

| Parameters | | |
|---|---|---|
| `page` | integer, optional, default `0` | Page number (0-based, default 0) |
| `page_size` | integer, optional, default `20` | Page size (default 20, max 100) |

#### `place_goal_driven_call` (write)

Place a REAL phone call to a number the customer gives you, to accomplish a stated goal (e.g. 'call this restaurant and ask if they have a table tonight'). A real-time voice assistant makes the call in the background; this only enqueues the request — the call is placed shortly after and cannot be recalled once dialing. Poll get_voice_call with the returned voice_call_request_id for the outcome (status, goal_achieved, summary, transcript); the result also arrives as a platform notification.

- `POST /rest/v1/tools/place_goal_driven_call`

| Parameters | | |
|---|---|---|
| `phone_number` | string, required | The phone number to call, international format e.g. +5511999999999 |
| `goal` | string, required | The goal of the call in plain language and the customer's language — exactly what to accomplish or find out |
| `context` | string, optional | Optional background/context: who is being called and any helpful info |

#### `set_campaign_voice_calling_active` (write)

Enable or disable autonomous outbound voice calls for a specific campaign, overriding the customer-level toggle for that campaign only.

- `POST /rest/v1/tools/set_campaign_voice_calling_active`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | Name of the campaign |
| `active` | boolean, required | True to enable, false to disable, for this campaign |

#### `set_voice_calling_active` (write)

Enable or disable autonomous outbound voice calls to leads at the customer level. Separate from email prospecting.

- `POST /rest/v1/tools/set_voice_calling_active`

| Parameters | | |
|---|---|---|
| `active` | boolean, required | True to enable, false to disable |

### WhatsApp line

Register and inspect the prospecting WhatsApp line, set its monthly and daily cost caps, and update its business profile.

#### `get_whatsapp_line` (read)

Get the customer's WhatsApp prospecting line — the one-stop status/diagnostic read: whether it is live/ready to send, its number, quality rating, full WhatsApp business profile, the pending one-click Meta signup link (when the customer still needs to connect their WhatsApp Business Account), any ACTIVE HEALTH ISSUE with the exact fix the customer must apply (payment method, reconnect link, Meta restriction), and the day- and month-to-date WhatsApp spend vs the customer's daily and monthly cost caps. Refreshes the live snapshot from Meta first.

- `POST /rest/v1/tools/get_whatsapp_line`
- `GET /rest/v1/call/get_whatsapp_line`

Parameters: —

#### `register_whatsapp_line` (write)

Register a dedicated WhatsApp prospecting line (a real WhatsApp number). Provisioning is automatic and takes a few minutes. If the customer already has a line, returns that line instead of creating another (one line per customer). Requires an active paid plan that includes WhatsApp prospecting. By default Eesier provides a brand-new number; pass use_own_number=true when the customer wants to prospect from their OWN WhatsApp number — they then receive a one-click Meta link whose official popup connects their WhatsApp Business Account (or creates one), lets them pick which of their numbers to use, or verifies a new number on the spot.

- `POST /rest/v1/tools/register_whatsapp_line`

| Parameters | | |
|---|---|---|
| `use_own_number` | boolean, optional, default `false` | True when the customer wants to use their OWN WhatsApp number instead of a new Eesier-provided one. Default false. |

#### `set_whatsapp_daily_cost_cap` (write)

Set (or clear) the customer's daily WhatsApp prospecting spending cap, in BRL. Meta bills WhatsApp conversation fees to the customer's own account, so this cap lets the customer decide the maximum they want to spend per day. When the cap is reached, paid (conversation-opening) WhatsApp messages pause until the next day — replies to leads who message first keep working, and email prospecting is unaffected. Pass 0 or a negative value to remove the cap. The current spend and cap are visible on get_whatsapp_line.

- `POST /rest/v1/tools/set_whatsapp_daily_cost_cap`

| Parameters | | |
|---|---|---|
| `daily_cap_brl` | number, required | Maximum daily WhatsApp spend in BRL (e.g. 20.00). 0 or negative removes the cap. |

#### `set_whatsapp_line_profile_picture` (write)

Set the WhatsApp line's profile picture from a public image URL or an already-uploaded customer file. Square JPG/PNG, at least 192x192, under 5MB. The line must already be live.

- `POST /rest/v1/tools/set_whatsapp_line_profile_picture`

| Parameters | | |
|---|---|---|
| `image_url` | string, optional | Public URL of the image (square JPG/PNG, >=192x192, <=5MB) |
| `customer_file_id` | integer, optional | Id of an already-uploaded customer file to use as the picture. Preferred when the user uploaded an image. |

#### `set_whatsapp_monthly_cost_cap` (write)

Set (or clear) the customer's monthly WhatsApp prospecting spending cap, in BRL. Meta bills WhatsApp conversation fees to the customer's own account, so this cap lets the customer decide the maximum they want to spend per calendar month. When the cap is reached, paid (conversation-opening) WhatsApp messages pause until the 1st of the next month — replies to leads who message first keep working, and email prospecting is unaffected. Pass 0 or a negative value to remove the cap. The current spend and cap are visible on get_whatsapp_line.

- `POST /rest/v1/tools/set_whatsapp_monthly_cost_cap`

| Parameters | | |
|---|---|---|
| `monthly_cap_brl` | number, required | Maximum monthly WhatsApp spend in BRL (e.g. 150.00). 0 or negative removes the cap. |

#### `update_whatsapp_line_profile` (write)

Update the WhatsApp line's business profile. Only provided fields change. The line must already be live. Display name is not managed here.

- `POST /rest/v1/tools/update_whatsapp_line_profile`

| Parameters | | |
|---|---|---|
| `about` | string, optional | Short 'about' text (max 139 chars) |
| `description` | string, optional | Business description (max 512 chars) |
| `address` | string, optional | Business street address |
| `email` | string, optional | Business contact email |
| `websites` | string, optional | Business website URLs, comma-separated (WhatsApp shows at most 2) |
| `vertical` | string, optional | Business category (WhatsApp vertical), e.g. PROF_SERVICES, RETAIL, EDU, HEALTH, FINANCE, RESTAURANT, OTHER |

### Business profile

What the account sells and to whom. Read the profile, read the agent's assessment of it, and rewrite it.

#### `get_business` (read)

Returns the customer's business profile: name, description, website, ideal customer profile, and default presentation URL.

- `POST /rest/v1/tools/get_business`
- `GET /rest/v1/call/get_business`

Parameters: —

#### `get_business_assessment` (read)

Read the last business-fundamentals assessment Blue Button's internal advisor recorded for this customer: verdict, results probability, the full assessment JSON, when it was made, and the customer's known paying-client examples. Read-only data — bring your own analysis on top of it; there is no tool to re-run the assessment.

- `POST /rest/v1/tools/get_business_assessment`
- `GET /rest/v1/call/get_business_assessment`

Parameters: —

#### `set_business` (write)

Updates the customer's business profile. Pass only the fields you want to change. Fields: business_name, business_description, business_website, ideal_customer_profile, paying_customer_examples. For the files the prospecting agent sends to leads (presentation, price table, ...), use the prospecting-file tools (register_prospecting_file / list_prospecting_files).

- `POST /rest/v1/tools/set_business`

| Parameters | | |
|---|---|---|
| `business_name` | string, optional | Business name |
| `business_description` | string, optional | Business description |
| `business_website` | string, optional | Business website URL |
| `ideal_customer_profile` | string, optional | Ideal customer profile text |
| `paying_customer_examples` | string, optional | Real paying-customer examples the ICP and the business advisor reason from |

### Business files

The reference material the agent reads to understand the business — register, list and remove it.

#### `list_business_files` (read)

List the business-knowledge files registered for this customer, with each file's indexing state and campaign scope.

- `POST /rest/v1/tools/list_business_files`
- `GET /rest/v1/call/list_business_files`

Parameters: —

#### `register_business_file` (write)

Register text (or an already-uploaded customer file) as business knowledge so the prospecting agents can answer questions about the business (services, processes, pricing, FAQs). The content is chunked + embedded in the background and becomes searchable shortly. Provide either text or customer_file_id.

- `POST /rest/v1/tools/register_business_file`

| Parameters | | |
|---|---|---|
| `title` | string, required | Short descriptive title, e.g. 'Tabela de precos 2026' |
| `text` | string, optional | Raw text to register as business knowledge (use when the content was pasted directly) |
| `customer_file_id` | integer, optional | Id of an existing customer file to register (find it with list_business_files or the file list) |
| `campaign` | string, optional | Optional campaign name to scope this knowledge to one campaign. Leave empty for customer-level knowledge shared across every campaign. |

#### `remove_business_file` (destructive)

Remove a registered business-knowledge file and its indexed chunks so the agents stop answering from it. Find the id with list_business_files.

- `POST /rest/v1/tools/remove_business_file`

| Parameters | | |
|---|---|---|
| `business_file_id` | integer, required | Id of the business knowledge file to remove |

### FAQ

The questions leads keep asking: the answered business FAQ, and the ones still open waiting for an answer.

#### `list_business_faq` (read)

List the business FAQ — every question-and-answer pair the platform has accumulated about this business (each answer given via answer_lead_question lands here, and the prospecting agents use it to answer leads). Read it before asking the user something that may already be answered.

- `POST /rest/v1/tools/list_business_faq`
- `GET /rest/v1/call/list_business_faq`

Parameters: —

#### `list_open_lead_questions` (read)

List the questions LEADS asked that the agent could not answer and that are still waiting for the business owner's input. High-value loop: surface these to the user, get the answers, then record each via answer_lead_question (pass the open_question_id) — every answer improves all future lead conversations.

- `POST /rest/v1/tools/list_open_lead_questions`
- `GET /rest/v1/call/list_open_lead_questions`

Parameters: —

### Suggestions

Ask the platform to draft targeting for you — an ideal customer profile, or the activity codes to include and exclude.

#### `generate_cnae_exclusion_suggestion` (read)

Generate suggested CNAE exclusion codes based on an ideal customer profile and business description. These codes identify competitors and bad-fit industries to exclude from prospecting. Only works for Brazilian customers. Returns codes without saving — use set_targeting to save.

- `POST /rest/v1/tools/generate_cnae_exclusion_suggestion`
- `GET /rest/v1/call/generate_cnae_exclusion_suggestion`

| Parameters | | |
|---|---|---|
| `icp_text` | string, optional | ICP text to analyze. If omitted, uses the customer's current ICP. |

#### `generate_cnae_suggestion` (read)

Generate suggested CNAE inclusion codes based on an ideal customer profile. CNAE codes are used to target specific industries in Brazilian lead prospecting. Only works for Brazilian customers. Returns codes without saving — use set_targeting to save.

- `POST /rest/v1/tools/generate_cnae_suggestion`
- `GET /rest/v1/call/generate_cnae_suggestion`

| Parameters | | |
|---|---|---|
| `icp_text` | string, optional | ICP text to analyze. If omitted, uses the customer's current ICP. |

#### `generate_icp_suggestion` (read)

Generate an ideal customer profile (ICP) suggestion based on the customer's business information. Uses AI to analyze the business and suggest who the ideal customers are. Returns the suggestion without saving it — use set_business to save.

- `POST /rest/v1/tools/generate_icp_suggestion`
- `GET /rest/v1/call/generate_icp_suggestion`

Parameters: —

### Reference lookups

Search the platform's own knowledge base before answering any question about how it works, and resolve activity codes and cities.

#### `lookup_city` (read)

Look up a Brazilian city code (código IBGE) from a city name. Only works for Brazilian customers. Returns matching cities. Used for city-based prospecting filters.

- `POST /rest/v1/tools/lookup_city`
- `GET /rest/v1/call/lookup_city`

| Parameters | | |
|---|---|---|
| `city_name` | string, required | City name to search for (e.g. 'São Paulo', 'Curitiba') |

#### `lookup_cnae` (read)

Look up a CNAE code's name and description. CNAE (Classificação Nacional de Atividades Econômicas) is the Brazilian industry classification system. Only works for Brazilian customers. Provide a code to get its name at division (2-digit), group (3-digit), class (5-digit), or subclass (7-digit) level.

- `POST /rest/v1/tools/lookup_cnae`
- `GET /rest/v1/call/lookup_cnae`

| Parameters | | |
|---|---|---|
| `code` | string, required | CNAE code (e.g. '62' for IT division, '6201' for software development group, '6201501' for software development subclass) |

#### `search_knowledge` (read)

Search the Blue Button knowledge base for authoritative answers about how the platform works — pricing, plans, onboarding, targeting capabilities, email sending, takeovers, reports, privacy, cancellation, and every other platform-specific question. Uses semantic RAG (embedding similarity) over curated knowledge pieces, so the query can be a natural-language question, a keyword, or a topic. ALWAYS call this tool whenever the user asks anything specific about Blue Button — never improvise from general knowledge. Returns the top matches with title, content, and similarity score.

- `POST /rest/v1/tools/search_knowledge`
- `GET /rest/v1/call/search_knowledge`

| Parameters | | |
|---|---|---|
| `query` | string, required | Natural-language query describing what the user wants to know about Blue Button (e.g. 'how much does it cost', 'can I target by company size', 'what happens when I take over a lead', 'international prospecting'). |
| `top_k` | integer, optional, default `3` | Number of top results to return. Default 3. Use a higher value (up to 10) when the question is broad or you want multiple angles. |
| `min_score` | number, optional, default `0.7` | Minimum similarity score threshold (0.0–1.0). Default 0.7. Lower values return more results but may be less relevant. |

### Blacklist

Never contact these again: block and unblock e-mail addresses, whole domains and phone numbers.

#### `add_blacklisted_domain` (write)

Add a whole DOMAIN to the blacklist. Every email at that domain (e.g. anyone@acme.com) is blocked. Do not pass a full email address — use add_blacklisted_email for that.

- `POST /rest/v1/tools/add_blacklisted_domain`

| Parameters | | |
|---|---|---|
| `domain` | string, required | The domain to blacklist, e.g. 'acme.com'. Subdomains are not auto-included. |
| `reason` | string, optional | Reason: Competitor, Client, or Other |

#### `add_blacklisted_email` (write)

Add a single email address to the blacklist. Blacklisted emails never receive prospecting messages. To block an entire company, use add_blacklisted_domain instead.

- `POST /rest/v1/tools/add_blacklisted_email`

| Parameters | | |
|---|---|---|
| `email` | string, required | The email address to blacklist |
| `reason` | string, optional | Reason: Competitor, Client, or Other |

#### `add_blacklisted_phone` (write)

Add a PHONE NUMBER to the blacklist. The number never receives a WhatsApp message or a voice call. Digits are kept and everything else is stripped, so any formatting is accepted.

- `POST /rest/v1/tools/add_blacklisted_phone`

| Parameters | | |
|---|---|---|
| `phone` | string, required | The phone number to blacklist, in any format (e.g. '+55 11 99999-9999') |
| `reason` | string, optional | Reason: Competitor, Client, or Other |

#### `list_blacklisted_emails` (read)

List blacklisted entries (individual emails, whole domains and phone numbers) with their reason and times-blocked count. Paginated — 'total' reports the full list size.

- `POST /rest/v1/tools/list_blacklisted_emails`
- `GET /rest/v1/call/list_blacklisted_emails`

| Parameters | | |
|---|---|---|
| `page` | integer, optional, default `0` | Page number (0-based, default 0) |
| `page_size` | integer, optional, default `50` | Entries per page (default 50, max 200) |

#### `remove_blacklisted_domain` (destructive)

Remove a whole DOMAIN from the blacklist, allowing addresses at that domain to receive prospecting messages again.

- `POST /rest/v1/tools/remove_blacklisted_domain`

| Parameters | | |
|---|---|---|
| `domain` | string, required | The domain to remove from the blacklist, e.g. 'acme.com' |

#### `remove_blacklisted_email` (destructive)

Remove a single email address from the blacklist, allowing it to receive prospecting messages again.

- `POST /rest/v1/tools/remove_blacklisted_email`

| Parameters | | |
|---|---|---|
| `email` | string, required | The email address to remove from the blacklist |

#### `remove_blacklisted_phone` (destructive)

Remove a PHONE NUMBER from the blacklist, allowing it to receive WhatsApp messages and voice calls again.

- `POST /rest/v1/tools/remove_blacklisted_phone`

| Parameters | | |
|---|---|---|
| `phone` | string, required | The phone number to remove from the blacklist, in any format |

### Account settings

Timezone, user name, preferences, call permission, notification e-mails, sending e-mail settings, sender domain setup, and tax data.

#### `get_email_settings` (read)

Get the customer's Blue Button email settings: the full address, handle, display name, and notification instructions.

- `POST /rest/v1/tools/get_email_settings`
- `GET /rest/v1/call/get_email_settings`

Parameters: —

#### `get_general_settings` (read)

Get the customer's general account settings: voice mode, autonomous-message sending, account email, and timezone offset.

- `POST /rest/v1/tools/get_general_settings`
- `GET /rest/v1/call/get_general_settings`

Parameters: —

#### `get_notification_emails` (read)

Get the email addresses currently set for autonomous prospecting notifications and daily reports.

- `POST /rest/v1/tools/get_notification_emails`
- `GET /rest/v1/call/get_notification_emails`

Parameters: —

#### `lookup_municipality_code` (read)

Look up the 7-digit IBGE municipality code for a Brazilian city. Returns all matches when the city exists in multiple states. Use before update_tax_info.

- `POST /rest/v1/tools/lookup_municipality_code`
- `GET /rest/v1/call/lookup_municipality_code`

| Parameters | | |
|---|---|---|
| `city_name` | string, required | Brazilian city name (accent-insensitive) |
| `state` | string, optional | Optional state — 2-letter UF (RS, SP...) or full Portuguese name — to disambiguate |

#### `set_agent_phone_call_permission` (write)

Get or set whether the agent may place outbound phone calls to the customer. Omit 'enabled' to read the current value; pass true/false to change it.

- `POST /rest/v1/tools/set_agent_phone_call_permission`

| Parameters | | |
|---|---|---|
| `enabled` | boolean, optional | True to allow calls, false to block. Omit to just read the current value. |

#### `set_email_notification_instructions` (write)

Set the free-text rules that decide which inbound emails deserve an immediate notification to the customer. Pass an empty string to clear them and fall back to the default behaviour.

- `POST /rest/v1/tools/set_email_notification_instructions`

| Parameters | | |
|---|---|---|
| `instructions` | string, required | Rules describing which inbound emails warrant an immediate heads-up (empty to clear) |

#### `set_personal_email` (write)

Set the account's own personal email address — the single address tied to the account itself, distinct from the comma-separated prospecting notification list managed by update_notification_emails.

- `POST /rest/v1/tools/set_personal_email`

| Parameters | | |
|---|---|---|
| `email` | string, required | The account owner's personal email address |

#### `set_timezone` (write)

Set the customer's timezone by telling the agent the current local hour (0-23, 24h format). The offset is computed from UTC.

- `POST /rest/v1/tools/set_timezone`

| Parameters | | |
|---|---|---|
| `current_hour` | integer, required | Hour part of the customer's current local time, 0-23 (24h format) |

#### `setup_custom_domain` (write)

Set up, verify, or remove a custom-domain email address (e.g. sales@yourcompany.com). Requires an active paid plan. action: 'activate' (needs email_address), 'verify', or 'remove'.

- `POST /rest/v1/tools/setup_custom_domain`

| Parameters | | |
|---|---|---|
| `action` | string, required | 'activate' to set a new custom email, 'verify' to check DNS, 'remove' to remove it |
| `email_address` | string, optional | The full custom email address, e.g. 'sales@yourcompany.com'. Required for 'activate'. |

#### `setup_email_subdomain` (write)

Set up or verify a custom email subdomain (e.g. yourcompany.eesiermail.com). Requires an active paid plan. action: 'activate' (needs subdomain) or 'verify'.

- `POST /rest/v1/tools/setup_email_subdomain`

| Parameters | | |
|---|---|---|
| `action` | string, required | 'activate' to set a new subdomain, 'verify' to check DNS verification status |
| `subdomain` | string, optional | The subdomain name, e.g. 'mycompany'. Required for 'activate'. |

#### `update_email_settings` (write)

Update the Blue Button email handle (the part before @, max 20 chars, unique) and/or the display name shown in outgoing emails. Pass at least one field.

- `POST /rest/v1/tools/update_email_settings`

| Parameters | | |
|---|---|---|
| `handle` | string, optional | New email handle (lowercase, no spaces, max 20 chars). Accents/invalid chars are stripped. |
| `display_name` | string, optional | New display name for outgoing emails (the 'From' name recipients see) |

#### `update_notification_emails` (write)

Set the email address(es) for autonomous prospecting notifications and daily reports (comma-separated). The first address also becomes the account email.

- `POST /rest/v1/tools/update_notification_emails`

| Parameters | | |
|---|---|---|
| `emails` | string, required | Email address(es) for notifications, comma-separated |

#### `update_preferences` (write)

Update customer preferences: language, whether to show the business on the Blue Button website, and push notifications. Pass at least one field.

- `POST /rest/v1/tools/update_preferences`

| Parameters | | |
|---|---|---|
| `language_key` | string, optional | Language key, e.g. pt-BR, en-US, es-AR |
| `show_on_website` | boolean, optional | Whether to show the business on the Blue Button website |
| `push_notifications` | boolean, optional | Whether push (console) notifications are enabled |

#### `update_tax_info` (write)

Update tax/invoice information. Pass whichever fields need updating. Tax document must be CPF (11 digits) or CNPJ (14 digits); CEP must be 8 digits; municipality code must be a valid 7-digit IBGE code (use lookup_municipality_code first).

- `POST /rest/v1/tools/update_tax_info`

| Parameters | | |
|---|---|---|
| `tax_name` | string, optional | Tax-registered name (company or person) |
| `tax_document` | string, optional | Tax document, digits only: CPF (11) or CNPJ (14) |
| `street` | string, optional | Street name |
| `number` | string, optional | Address number |
| `neighborhood` | string, optional | Neighborhood |
| `cep` | string, optional | Postal code (CEP, 8 digits) |
| `municipality_code` | integer, optional | IBGE municipality code (7 digits) |

#### `update_user_name` (write)

Update the customer's display name.

- `POST /rest/v1/tools/update_user_name`

| Parameters | | |
|---|---|---|
| `name` | string, required | The new name for the customer |

### Team members

Who else is on the account — add, list and remove members.

#### `add_member` (write)

Add another person (an additional phone number) to this account. They get their own conversation with the agent but full shared access to the same company, settings, and prospecting. Fails if the phone number already belongs to any account.

- `POST /rest/v1/tools/add_member`

| Parameters | | |
|---|---|---|
| `name` | string, required | The person's name |
| `phone_number` | string, required | The person's phone number in international format, e.g. +5511999999999 |
| `email` | string, optional | Optional email — when set, they receive copies of email notifications (interested/confirmed-lead emails) |

#### `list_members` (read)

List everyone on this account: the account owner plus any additional people that were added.

- `POST /rest/v1/tools/list_members`
- `GET /rest/v1/call/list_members`

Parameters: —

#### `remove_member` (destructive)

Remove an additional person from this account, identified by name or phone number. The account owner cannot be removed.

- `POST /rest/v1/tools/remove_member`

| Parameters | | |
|---|---|---|
| `name_or_phone` | string, required | The name or phone number of the person to remove |

### Access tokens

Manage the tokens that authenticate this connection: list them, issue a new one, revoke one.

#### `generate_mcp_token` (write)

Create a new MCP access token for this account. The token value is returned ONCE and never again — pass it to the caller immediately and tell them to store it securely.

- `POST /rest/v1/tools/generate_mcp_token`

| Parameters | | |
|---|---|---|
| `label` | string, optional | A short label naming what will use this token, e.g. 'n8n workflow' |

#### `list_mcp_tokens` (read)

List the account's MCP access tokens. The token values themselves are never returned — only the id, label, creation date, last-used date and whether the token has been revoked.

- `POST /rest/v1/tools/list_mcp_tokens`
- `GET /rest/v1/call/list_mcp_tokens`

Parameters: —

#### `revoke_mcp_token` (destructive)

Revoke an MCP access token so it can no longer connect. Use list_mcp_tokens to find the token_id. Revoking the token the caller is currently authenticated with immediately ends their own access.

- `POST /rest/v1/tools/revoke_mcp_token`

| Parameters | | |
|---|---|---|
| `token_id` | integer, required | The id of the token to revoke, from list_mcp_tokens |

### Events & webhooks

The account event feed with a cursor, plus outbound webhook subscriptions — create, list, test and delete them.

#### `create_webhook_subscription` (write)

Register an HTTPS webhook endpoint that receives account events as they happen (signed POSTs) — for automation systems the customer runs (Agent SDK apps, n8n, Zapier, custom backends). The signing secret is returned ONCE in this response — store it securely. Note: this does NOT push into this MCP session; agents that can only poll should use list_account_events instead.

- `POST /rest/v1/tools/create_webhook_subscription`

| Parameters | | |
|---|---|---|
| `url` | string, required | The HTTPS endpoint to POST events to |
| `event_types` | string, optional | Comma-separated event types to deliver (optional; default = all). Same values as list_account_events. |
| `description` | string, optional | A short label for this subscription (e.g. 'my n8n flow') |

#### `delete_webhook_subscription` (destructive)

Delete a webhook subscription — deliveries to its endpoint stop immediately. Irreversible (create a new subscription to resume; it will get a new secret).

- `POST /rest/v1/tools/delete_webhook_subscription`

| Parameters | | |
|---|---|---|
| `subscription_id` | integer, required | Subscription ID (from list_webhook_subscriptions) |

#### `list_account_events` (read)

Poll the account's event feed — new lead replies (email/WhatsApp), leads flagged for review, leads becoming interested/confirmed, meetings booked/cancelled, voice calls finished, imports finished, support answered. Cursor-paged: pass the next_cursor from the previous call to get only what happened since. This is about ACCOUNT ACTIVITY — not calendar events (list_calendar_events / list_calendly_upcoming_events) and not one lead's history (list_lead_lifecycle_events).

- `POST /rest/v1/tools/list_account_events`
- `GET /rest/v1/call/list_account_events`

| Parameters | | |
|---|---|---|
| `since_cursor` | integer, optional, default `0` | Return only events with id greater than this (0 = from the beginning of the feed). Use the next_cursor from the previous call. |
| `event_types` | string, optional | Comma-separated event types to include (optional; default = all). Valid: lead_replied_email, lead_replied_whatsapp, lead_sent_for_human_review, lead_became_interested, lead_confirmed, meeting_booked, meeting_cancelled, voice_call_finished, import_finished, support_request_answered |
| `limit` | integer, optional, default `50` | Max events to return (default 50, max 200) |

#### `list_webhook_subscriptions` (read)

List the account's webhook subscriptions with delivery health (last success/failure, consecutive failures, disabled state). Secrets are never shown again.

- `POST /rest/v1/tools/list_webhook_subscriptions`
- `GET /rest/v1/call/list_webhook_subscriptions`

Parameters: —

#### `test_webhook_subscription` (write)

Send a signed test 'ping' event to a webhook subscription's endpoint so the customer can verify their receiver and signature check. The delivery result appears in list_webhook_subscriptions (date_last_success / last_failure_reason) within ~1 minute.

- `POST /rest/v1/tools/test_webhook_subscription`

| Parameters | | |
|---|---|---|
| `subscription_id` | integer, required | Subscription ID (from list_webhook_subscriptions) |

### CRM integrations

Connect and disconnect a CRM, check sync status, force a resync, map custom fields, and manage the Apollo, Lusha and RD Station links.

#### `connect_crm` (write)

Connect a CRM integration. Each CRM needs different credentials: Pipedrive (api_key), RdStation (marketing_api_key and/or crm_token), HubSpot (access_token), Odoo (url + database + username + api_key), Omie (app_key + app_secret), Agendor/ExactSales/Piperun/Venttra (api_token), SystemeIo (api_key). Requires an active paid plan. The credential is LIVE-VERIFIED against the provider before being stored (a bad key returns an error and stores nothing); the response's 'verified' field says whether verification was possible — ExactSales, Piperun, Venttra, and the RdStation marketing key are write-only APIs and are stored unverified.

- `POST /rest/v1/tools/connect_crm`

| Parameters | | |
|---|---|---|
| `crm_name` | string, required | CRM name: Pipedrive, RdStation, HubSpot, Odoo, Omie, Agendor, ExactSales, Piperun, SystemeIo, Venttra |
| `api_key` | string, optional | API key (Pipedrive, Odoo, SystemeIo) |
| `api_token` | string, optional | API token (Agendor, ExactSales, Piperun, Venttra) |
| `access_token` | string, optional | Access token (HubSpot) |
| `url` | string, optional | URL (Odoo) |
| `database` | string, optional | Database name (Odoo) |
| `username` | string, optional | Username (Odoo) |
| `app_key` | string, optional | App key (Omie) |
| `app_secret` | string, optional | App secret (Omie) |
| `marketing_api_key` | string, optional | Marketing API key (RdStation) |
| `crm_token` | string, optional | CRM token (RdStation) |
| `pipeline_id` | integer, optional | Pipeline id deals are created in (Pipedrive) |
| `funnel_id` | integer, optional | Funnel id deals are created in (Agendor) |

#### `disconnect_crm` (destructive)

Disconnect a CRM integration by clearing its credentials.

- `POST /rest/v1/tools/disconnect_crm`

| Parameters | | |
|---|---|---|
| `crm_name` | string, required | CRM name: Pipedrive, RdStation, HubSpot, Odoo, Omie, Agendor, ExactSales, Piperun, SystemeIo, Venttra |

#### `get_crm_sync_status` (read)

Show how many leads have been synced to each connected CRM: synced, pending, and stuck counts, the last sync time, and a few recently-synced lead names.

- `POST /rest/v1/tools/get_crm_sync_status`
- `GET /rest/v1/call/get_crm_sync_status`

Parameters: —

#### `list_crm_integrations` (read)

List all CRM integrations with their connection status, the minimum lead status filter for CRM sync, and the configured custom fields.

- `POST /rest/v1/tools/list_crm_integrations`
- `GET /rest/v1/call/list_crm_integrations`

Parameters: —

#### `manage_apollo_integration` (write)

Connect or disconnect the Apollo lead-source integration. Requires an active paid plan. action: 'connect' (needs api_key) or 'disconnect'. The api_key is live-verified against Apollo before being stored — a bad key returns an error and stores nothing.

- `POST /rest/v1/tools/manage_apollo_integration`

| Parameters | | |
|---|---|---|
| `action` | string, required | Action: connect or disconnect |
| `api_key` | string, optional | Apollo API key (required for connect) |
| `list_id` | string, optional | Apollo list id to sync leads from (optional) |

#### `manage_crm_custom_fields` (write)

Manage custom fields sent with every lead to CRM integrations. action: 'list', 'add' (needs field_name + field_value), or 'remove' (needs field_id).

- `POST /rest/v1/tools/manage_crm_custom_fields`

| Parameters | | |
|---|---|---|
| `action` | string, required | Action: list, add, or remove |
| `field_name` | string, optional | Field name (required for 'add') |
| `field_value` | string, optional | Field value (required for 'add') |
| `field_id` | integer, optional | Field id (required for 'remove') |

#### `manage_lusha_integration` (write)

Connect or disconnect the Lusha lead-source integration. Requires an active paid plan. action: 'connect' (needs api_key) or 'disconnect'. The api_key is live-verified against Lusha before being stored — a bad key returns an error and stores nothing.

- `POST /rest/v1/tools/manage_lusha_integration`

| Parameters | | |
|---|---|---|
| `action` | string, required | Action: connect or disconnect |
| `api_key` | string, optional | Lusha API key (required for connect) |
| `list_id` | string, optional | Lusha list id to sync leads from (optional) |

#### `manage_rd_station_crm_lead_source` (write)

Enable or disable importing RD Station CRM contacts as prospecting leads. Requires an active paid plan and the RD Station CRM token to already be connected (use connect_crm). action: 'enable' (optionally scoped by pipeline_id and deal_stage_id so only contacts attached to deals there are imported) or 'disable'. Enabling live-verifies the stored token against RD Station CRM first. Does not affect the outbound lead-to-CRM sync.

- `POST /rest/v1/tools/manage_rd_station_crm_lead_source`

| Parameters | | |
|---|---|---|
| `action` | string, required | Action: enable or disable |
| `pipeline_id` | string, optional | RD Station CRM deal pipeline id to limit the import to (optional; omit to import all contacts) |
| `deal_stage_id` | string, optional | RD Station CRM deal stage id inside the pipeline to limit the import to (optional; requires pipeline_id) |

#### `resync_crm_leads` (write)

Manually re-queue eligible leads that have not yet been sent to the CRM so the background sync retries them. Already-synced leads are never re-sent (no duplicates). The send happens in the background within a few minutes.

- `POST /rest/v1/tools/resync_crm_leads`

Parameters: —

#### `update_crm_minimum_status` (write)

Set the minimum lead status required before a lead is synced to the CRM (Pending, Cold, Confirmed, Aware, NotInterested, Interested). Omit 'status' to clear the filter and sync all leads.

- `POST /rest/v1/tools/update_crm_minimum_status`

| Parameters | | |
|---|---|---|
| `status` | string, optional | Minimum lead status for CRM sync. Omit to sync all leads. |

### Calendly

Connect Calendly, pick the event type leads get booked into, and read upcoming bookings.

#### `disconnect_calendly` (destructive)

Disconnects the customer's Calendly account: deletes the webhook subscription on Calendly's side, revokes the access token, and clears all stored Calendly fields. Pass user_has_confirmed=true only when the user has explicitly confirmed they want to disconnect.

- `POST /rest/v1/tools/disconnect_calendly`

| Parameters | | |
|---|---|---|
| `user_has_confirmed` | boolean, required | Must be true — the agent must have explicit user confirmation before disconnecting. |

#### `get_calendly_connection_url` (read)

Returns the URL the user must click to connect their Calendly account to Eesier. Share this URL with the user — they open it, sign into Calendly, click Authorize, and the connection is established server-side. After the user completes the flow, call get_calendly_status again to confirm. Idempotent: returns the same URL whether or not Calendly is already connected (so the user can reconnect a different account).

- `POST /rest/v1/tools/get_calendly_connection_url`
- `GET /rest/v1/call/get_calendly_connection_url`

Parameters: —

#### `get_calendly_event` (read)

Returns full details for a specific scheduled Calendly event, including the list of invitees with their names, emails, status, and any answers they gave to scheduling questions. Use this for follow-up questions about a specific meeting after list_calendly_upcoming_events.

- `POST /rest/v1/tools/get_calendly_event`
- `GET /rest/v1/call/get_calendly_event`

| Parameters | | |
|---|---|---|
| `event_uri` | string, required | Full Calendly scheduled event URI (e.g. 'https://api.calendly.com/scheduled_events/'). Get it from list_calendly_upcoming_events. |

#### `get_calendly_status` (read)

Returns the current Calendly connection status for the customer: whether OAuth is connected, the connected Calendly account email, and which event type (if any) is selected as the default for prospecting links.

- `POST /rest/v1/tools/get_calendly_status`
- `GET /rest/v1/call/get_calendly_status`

Parameters: —

#### `list_calendly_event_types` (read)

Lists all active event types in the customer's Calendly account (e.g. '15-min intro call', '30-min consultation'). Each entry includes uri (use this when calling set_calendly_default_event_type), name, slug, duration_minutes, scheduling_url, and is_default. Required: Calendly must be connected first.

- `POST /rest/v1/tools/list_calendly_event_types`
- `GET /rest/v1/call/list_calendly_event_types`

Parameters: —

#### `list_calendly_upcoming_events` (read)

Lists scheduled Calendly events on the customer's calendar within a date range. Use this for 'what's on my agenda' / 'do I have any meetings tomorrow' style requests. Returned `start_utc`/`end_utc` come back in UTC — pull `timezone_offset_utc_hours` from `whoami` and convert before showing them to the user. Calendly imposes a 100-day max range.

- `POST /rest/v1/tools/list_calendly_upcoming_events`
- `GET /rest/v1/call/list_calendly_upcoming_events`

| Parameters | | |
|---|---|---|
| `start_date` | string, optional | Start of the window in YYYY-MM-DD format (UTC, inclusive). Defaults to today's UTC date if omitted. |
| `end_date` | string, optional | End of the window in YYYY-MM-DD format (UTC, INCLUSIVE — events at any time on this day are returned). Defaults to 7 days after start_date. |
| `status` | string, optional, default `active` | Status filter: 'active' (default — confirmed bookings) or 'canceled'. |

#### `set_calendly_default_event_type` (write)

Sets the default Calendly event type. The default is the event type Blue Button uses when generating scheduling links inside lead conversations. Pass either event_type_uri (preferred — get it from list_calendly_event_types) or event_type_name (fuzzy-matched against active event types). Pass empty event_type_uri to clear the default.

- `POST /rest/v1/tools/set_calendly_default_event_type`

| Parameters | | |
|---|---|---|
| `event_type_uri` | string, optional | Full Calendly event type URI (preferred). Pass empty string to clear the current default. |
| `event_type_name` | string, optional | Or the event type's display name — fuzzy-matched against the customer's active event types. Used only when event_type_uri is not provided. |

### Google Calendar

Connect Google Calendar and work the calendar itself: list, create, update, delete and respond to events.

#### `create_calendar_event` (write)

Create a Google Calendar event. Times are UTC — convert the customer's local time using timezone_offset_utc_hours from whoami BEFORE calling. Returns the event id and a Meet link when one was generated.

- `POST /rest/v1/tools/create_calendar_event`

| Parameters | | |
|---|---|---|
| `summary` | string, required | Event title |
| `start_utc` | string, required | Event start in UTC, ISO format (e.g. 2026-07-10T14:00:00Z) |
| `end_utc` | string, required | Event end in UTC, ISO format |
| `attendees` | string, optional | Comma-separated attendee emails |
| `calendar_id` | string, optional, default `primary` | Calendar ID (default 'primary') |

#### `delete_calendar_event` (destructive)

Delete a Google Calendar event. This cancels the event for all attendees and cannot be undone.

- `POST /rest/v1/tools/delete_calendar_event`

| Parameters | | |
|---|---|---|
| `event_id` | string, required | ID of the calendar event |
| `calendar_id` | string, optional, default `primary` | Calendar ID (default 'primary') |

#### `get_google_connection_url` (read)

Get the OAuth URL for the customer to connect their Google account (required for the Google Calendar tools). Share the URL with the user; the connection completes server-side after they authorize. Idempotent — also works for reconnecting.

- `POST /rest/v1/tools/get_google_connection_url`
- `GET /rest/v1/call/get_google_connection_url`

Parameters: —

#### `list_calendar_events` (read)

List the customer's Google Calendar events for one calendar day (UTC). Returns start/end in UTC ISO format.

- `POST /rest/v1/tools/list_calendar_events`
- `GET /rest/v1/call/list_calendar_events`

| Parameters | | |
|---|---|---|
| `date` | string, required | The day to list, yyyy-MM-dd (interpreted in UTC) |
| `calendar_id` | string, optional, default `primary` | Calendar ID (default 'primary') |

#### `respond_calendar_event` (write)

Accept or decline a Google Calendar event invitation on the customer's behalf.

- `POST /rest/v1/tools/respond_calendar_event`

| Parameters | | |
|---|---|---|
| `event_id` | string, required | ID of the calendar event |
| `accept` | boolean, required | true to accept the invitation, false to decline |
| `calendar_id` | string, optional, default `primary` | Calendar ID (default 'primary') |

#### `update_calendar_event` (write)

Update a Google Calendar event (title, times, attendees). Pass only the fields to change. Times are UTC.

- `POST /rest/v1/tools/update_calendar_event`

| Parameters | | |
|---|---|---|
| `event_id` | string, required | ID of the calendar event |
| `summary` | string, optional | New event title |
| `start_utc` | string, optional | New start in UTC, ISO format |
| `end_utc` | string, optional | New end in UTC, ISO format |
| `attendees` | string, optional | New comma-separated attendee emails (replaces the current list) |
| `calendar_id` | string, optional, default `primary` | Calendar ID (default 'primary') |

### Google Ads

The paid side: campaigns, budgets, billing, performance reports, diagnostics, ad groups, keywords, negatives, search ads and audiences.

#### `add_google_ads_keywords` (write)

Add keywords to an ad group in a Google Ads campaign. One keyword per line in the keywords parameter (keywords may contain commas). match_type: Broad, Phrase, or Exact (default Broad).

- `POST /rest/v1/tools/add_google_ads_keywords`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |
| `ad_group_id` | integer, required | The ad group id (from list_google_ads_ad_groups) |
| `keywords` | string, required | The keywords to add, ONE PER LINE |
| `match_type` | string, optional | Match type: Broad (default), Phrase, or Exact |

#### `add_google_ads_negative_keywords` (write)

Add CAMPAIGN-LEVEL negative keywords to a Google Ads campaign (searches these terms will never trigger ads). One keyword per line. match_type: Broad (default), Phrase, or Exact.

- `POST /rest/v1/tools/add_google_ads_negative_keywords`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |
| `keywords` | string, required | The negative keywords to add, ONE PER LINE |
| `match_type` | string, optional | Match type: Broad (default), Phrase, or Exact |

#### `create_google_ads_campaign_draft` (write)

Create a NEW Google Ads campaign as a DRAFT. It does NOT serve until the customer recharges its balance via the returned console recharge_url — share that link and never claim the campaign is live. channel_type: Search (default) or PerformanceMax (only recommend PMax after a Search campaign has real conversion data).

- `POST /rest/v1/tools/create_google_ads_campaign_draft`

| Parameters | | |
|---|---|---|
| `name` | string, required | The campaign name as it will appear in Google Ads |
| `daily_budget_brl` | number, required | Daily budget in BRL (positive, e.g. 20) |
| `channel_type` | string, optional | Channel type: Search (default) or PerformanceMax |

#### `create_google_ads_search_ad` (write)

Create a Responsive Search Ad in an ad group of a Google Ads campaign. Headlines max 30 chars each, descriptions max 90 chars each — ONE PER LINE. Provide at least 3 headlines and 2 descriptions.

- `POST /rest/v1/tools/create_google_ads_search_ad`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |
| `ad_group_id` | integer, required | The ad group id (from list_google_ads_ad_groups) |
| `final_url` | string, required | The landing page URL the ad clicks through to |
| `headlines` | string, required | The ad headlines, ONE PER LINE, max 30 characters each |
| `descriptions` | string, required | The ad descriptions, ONE PER LINE, max 90 characters each |

#### `diagnose_google_ads_campaign` (read)

Diagnose why a Google Ads campaign is (or isn't) serving: live serving status, primary status with reasons, and per-ad approval/review status.

- `POST /rest/v1/tools/diagnose_google_ads_campaign`
- `GET /rest/v1/call/diagnose_google_ads_campaign`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |

#### `get_google_ads_audience_status` (read)

Get a Google Ads campaign's Customer Match audience status: how many emails were on the last upload, when, and whether the list is attached.

- `POST /rest/v1/tools/get_google_ads_audience_status`
- `GET /rest/v1/call/get_google_ads_audience_status`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |

#### `get_google_ads_billing` (read)

Read Google Ads billing/funding data for a campaign's account. section: AccountInfo, AccountBudgets, BillingSetups, Proposals, Invoices (needs year+month), or CampaignBudgets.

- `POST /rest/v1/tools/get_google_ads_billing`
- `GET /rest/v1/call/get_google_ads_billing`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |
| `section` | string, required | Section: AccountInfo, AccountBudgets, BillingSetups, Proposals, Invoices, CampaignBudgets |
| `year` | integer, optional | Invoice issue year (Invoices only) |
| `month` | integer, optional | Invoice issue month 1-12 (Invoices only) |

#### `get_google_ads_campaign` (read)

Get one Google Ads campaign's full detail: lifecycle status, hold reason, funding balance, the stored performance snapshot (spend, impressions, clicks, conversions, CTR, CPC), and the console management/recharge link. Pass the campaign name or id.

- `POST /rest/v1/tools/get_google_ads_campaign`
- `GET /rest/v1/call/get_google_ads_campaign`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id (from list_google_ads_campaigns) |

#### `get_google_ads_keyword_ideas` (read)

Get keyword ideas with search volume from Google's Keyword Planner for a campaign. Provide seed keywords (one per line) and/or a page URL to extract ideas from.

- `POST /rest/v1/tools/get_google_ads_keyword_ideas`
- `GET /rest/v1/call/get_google_ads_keyword_ideas`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |
| `seed_keywords` | string, optional | Seed keywords, ONE PER LINE |
| `page_url` | string, optional | A page URL to extract keyword ideas from |
| `max_results` | integer, optional, default `50` | Max results (default 50) |

#### `get_google_ads_performance_report` (read)

Pull a LIVE Google Ads performance report for a campaign. report_type: Campaign (totals), AdGroup, Keyword (with quality score), Ad, SearchTerms (what users actually searched), Daily, Device, Conversion, ImpressionShare (share of impressions + % lost to budget vs rank), AdAssets (per-headline/description LOW/GOOD/BEST labels), Hourly, Geographic, Demographics. Costs in BRL.

- `POST /rest/v1/tools/get_google_ads_performance_report`
- `GET /rest/v1/call/get_google_ads_performance_report`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |
| `report_type` | string, required | Report type: Campaign, AdGroup, Keyword, Ad, SearchTerms, Daily, Device, Conversion, ImpressionShare, AdAssets, Hourly, Geographic, Demographics |
| `date_range` | string, optional | Date range: a preset (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, THIS_MONTH, LAST_MONTH) or a custom 'yyyy-MM-dd AND yyyy-MM-dd' window. Default LAST_30_DAYS. |

#### `list_google_ads_ad_groups` (read)

List a Google Ads campaign's ad groups (id, name, status, CPC bid). Ad-group ids are needed for the keyword and ad tools.

- `POST /rest/v1/tools/list_google_ads_ad_groups`
- `GET /rest/v1/call/list_google_ads_ad_groups`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |

#### `list_google_ads_campaigns` (read)

List the customer's Google Ads campaigns with status, channel type, daily budget, hold reason, and balance (recharged, spent, remaining) — all in BRL. The entry point: call this first, then pass a returned name or id to the other google_ads tools.

- `POST /rest/v1/tools/list_google_ads_campaigns`
- `GET /rest/v1/call/list_google_ads_campaigns`

Parameters: —

#### `list_google_ads_keywords` (read)

List the keywords of one ad group in a Google Ads campaign (text, match type, status, CPC bid, quality score).

- `POST /rest/v1/tools/list_google_ads_keywords`
- `GET /rest/v1/call/list_google_ads_keywords`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |
| `ad_group_id` | integer, required | The ad group id (from list_google_ads_ad_groups) |

#### `nudge_google_ads_provisioning` (write)

Re-run the go-live provisioning gate for a Google Ads campaign that seems stuck after being funded (nudges the provisioning state machine forward).

- `POST /rest/v1/tools/nudge_google_ads_provisioning`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |

#### `refresh_google_ads_audience` (write)

Re-upload the Google Ads campaign's Customer Match audience from the customer's current lead emails (keeps the remarketing list fresh). Returns the number of emails uploaded.

- `POST /rest/v1/tools/refresh_google_ads_audience`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |

#### `set_google_ads_campaign_status` (destructive)

Pause, resume, or END a Google Ads campaign. Resume is gated on remaining balance + at least one enabled ad (and keyword for Search). END IS IRREVERSIBLE — it removes the campaign in Google Ads; get the customer's explicit confirmation before ending.

- `POST /rest/v1/tools/set_google_ads_campaign_status`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |
| `action` | string, required | Action: Pause, Resume, or End (End is irreversible) |

#### `sync_google_ads_spend` (write)

Refresh a Google Ads campaign's spend from the live Google API (updates the stored snapshot and funding math). Call this before quoting spend or balance numbers to the customer.

- `POST /rest/v1/tools/sync_google_ads_spend`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |

#### `update_google_ads_campaign_budget` (write)

Update a Google Ads campaign's daily budget (BRL). Returns the effective value after platform clamping.

- `POST /rest/v1/tools/update_google_ads_campaign_budget`

| Parameters | | |
|---|---|---|
| `campaign` | string, required | The campaign name or id |
| `new_daily_budget_brl` | number, required | The new daily budget in BRL |

### Websites

Register a site and change it by conversation: settings, subdomain, source code, snapshots and restores, screenshots, and crawling.

#### `archive_website` (destructive)

Archive (remove) a website.

- `POST /rest/v1/tools/archive_website`

| Parameters | | |
|---|---|---|
| `website_id` | integer, required | Id of the website to archive |

#### `cancel_website_change` (destructive)

Cancel the ongoing (unfinished) change request for a website.

- `POST /rest/v1/tools/cancel_website_change`

| Parameters | | |
|---|---|---|
| `website_id` | integer, required | Id of the website |

#### `change_website` (write)

Request a change to a website. The change is queued and rendered in the background — this returns immediately with a code id; poll get_website for completion.

- `POST /rest/v1/tools/change_website`

| Parameters | | |
|---|---|---|
| `website_id` | integer, required | Id of the website to change |
| `prompt` | string, required | Prompt describing the desired change |
| `data_storage_required` | boolean, optional, default `false` | True if the change requires data storage (a database) |
| `ignore_existing_code` | boolean, optional, default `false` | True to ignore the existing code and rebuild from scratch (full overhaul) |
| `reasoning_mode` | string, optional | Coding agent reasoning: Fast (simple changes, default) or Thinking (complex changes) |
| `generation_type` | string, optional | Generation type: Fast (default) or Quality |

#### `change_website_subdomain` (write)

Change a website's subdomain (the part before .eesier.website).

- `POST /rest/v1/tools/change_website_subdomain`

| Parameters | | |
|---|---|---|
| `website_id` | integer, required | Id of the website |
| `new_subdomain` | string, required | New subdomain part without the .eesier.website suffix (letters, numbers, hyphens only) |

#### `crawl_website` (read)

Fetch the raw HTML of a webpage, split into 1000-character chunks navigable by index.

- `POST /rest/v1/tools/crawl_website`
- `GET /rest/v1/call/crawl_website`

| Parameters | | |
|---|---|---|
| `url` | string, required | URL of the webpage to fetch |
| `chunk_index` | integer, optional, default `0` | Index of the chunk to return (starting at 0) |

#### `create_website_snapshot` (write)

Create a snapshot of a website's current code, tagged with a description, so it can be restored later.

- `POST /rest/v1/tools/create_website_snapshot`

| Parameters | | |
|---|---|---|
| `website_id` | integer, required | Id of the website |
| `snapshot_description` | string, required | Description for the snapshot |

#### `export_website_code` (write)

Export a website's current code to an HTML file and email it to the given address.

- `POST /rest/v1/tools/export_website_code`

| Parameters | | |
|---|---|---|
| `website_id` | integer, required | Id of the website |
| `email_address` | string, required | Destination email address |

#### `get_website` (read)

Get full information about one website: title, URL, type, language, generation status, and code-editor link.

- `POST /rest/v1/tools/get_website`
- `GET /rest/v1/call/get_website`

| Parameters | | |
|---|---|---|
| `website_id` | integer, required | Id of the website |

#### `get_website_code` (read)

Get the HTML code of a specific website code entry.

- `POST /rest/v1/tools/get_website_code`
- `GET /rest/v1/call/get_website_code`

| Parameters | | |
|---|---|---|
| `website_code_id` | integer, required | Id of the website code entry |

#### `get_website_settings` (read)

Get a website's configurable settings (title, language, restriction, agent guidelines).

- `POST /rest/v1/tools/get_website_settings`
- `GET /rest/v1/call/get_website_settings`

| Parameters | | |
|---|---|---|
| `website_id` | integer, required | Id of the website |

#### `list_website_code` (read)

List the successful code generations for a website (without the HTML itself), newest first.

- `POST /rest/v1/tools/list_website_code`
- `GET /rest/v1/call/list_website_code`

| Parameters | | |
|---|---|---|
| `website_id` | integer, required | Id of the website |

#### `list_website_snapshots` (read)

List a website's snapshots (saved code versions), newest first.

- `POST /rest/v1/tools/list_website_snapshots`
- `GET /rest/v1/call/list_website_snapshots`

| Parameters | | |
|---|---|---|
| `website_id` | integer, required | Id of the website |

#### `list_websites` (read)

List all of the customer's websites with their generation status, URL, and code-editor link.

- `POST /rest/v1/tools/list_websites`
- `GET /rest/v1/call/list_websites`

Parameters: —

#### `register_website` (write)

Register a new AI-generated website. Generation runs in the background — this returns immediately with an id; poll get_website / list_websites for the finished URL and status.

- `POST /rest/v1/tools/register_website`

| Parameters | | |
|---|---|---|
| `description` | string, required | Concise but complete description of the website: purpose, main features, target audience, style, and what it sells/promotes |
| `language` | string, required | Language code in xx-xx form, e.g. pt-br, en-us |
| `application_type` | string, optional | Application type: Website (default) or LeadCapturePage. For an interactive site with logins/dashboards, keep Website and set data_storage_required=true. |
| `generation_type` | string, optional | Generation type: Fast (default, simpler sites) or Quality (slower, better for complex sites) |
| `data_storage_required` | boolean, optional, default `false` | True if the site needs persistent data storage (accounts, orders, dashboards); false for static sites. Default false. |
| `restricted` | boolean, optional, default `false` | True to restrict the site behind a login page; false for public. Default false. |
| `copy_from_website_id` | integer, optional | Optional id of another of this customer's websites to copy code from |
| `business_or_brand_name` | string, optional | Optional name of the existing business/brand the site is for (triggers online research for content and branding) |

#### `restore_website_snapshot` (destructive)

Restore a snapshot (or any past code entry) as the website's current code.

- `POST /rest/v1/tools/restore_website_snapshot`

| Parameters | | |
|---|---|---|
| `website_code_id` | integer, required | Id of the website code entry to restore |

#### `screenshot_website` (write)

Take a screenshot of any public URL and analyze it with AI. Saves the screenshot as a customer file and returns the analysis + public image URL. Optionally emails the screenshot.

- `POST /rest/v1/tools/screenshot_website`

| Parameters | | |
|---|---|---|
| `url` | string, required | Public URL to capture |
| `prompt` | string, required | Prompt/instructions for the AI analysis |
| `viewport_width` | integer, optional, default `1366` | Viewport width in px (default 1366) |
| `viewport_height` | integer, optional, default `768` | Viewport height in px (default 768) |
| `send_to_email` | string, optional | Optional email address to send the screenshot to |
| `screenshot_file_name` | string, optional | Optional one-word file name for the screenshot |

#### `set_website_settings` (write)

Update a website's settings. Pass only the fields you want to change.

- `POST /rest/v1/tools/set_website_settings`

| Parameters | | |
|---|---|---|
| `website_id` | integer, required | Id of the website |
| `title` | string, optional | Website title (max 60 characters) |
| `language_key` | string, optional | Language key, e.g. pt-BR, en-US |
| `restricted` | boolean, optional | Whether the website is restricted behind a login |
| `guidelines` | string, optional | Persistent guidelines for how the agent should work on this website |

### Lead capture pages

The inbound side: create capture pages, change them, list them and archive them.

#### `archive_lead_capture_page` (destructive)

Archive (remove) a lead-capture page.

- `POST /rest/v1/tools/archive_lead_capture_page`

| Parameters | | |
|---|---|---|
| `lead_capture_page_id` | integer, required | Id of the lead-capture page |

#### `change_lead_capture_page` (write)

Request a change to a lead-capture page. The change is queued and rendered in the background — this returns immediately with a code id.

- `POST /rest/v1/tools/change_lead_capture_page`

| Parameters | | |
|---|---|---|
| `lead_capture_page_id` | integer, required | Id of the lead-capture page |
| `prompt` | string, required | Prompt describing the desired change |

#### `create_lead_capture_page` (write)

Create a lead-capture page. Generation runs in the background — this returns immediately with an id; poll list_lead_capture_pages for the finished URL.

- `POST /rest/v1/tools/create_lead_capture_page`

| Parameters | | |
|---|---|---|
| `description` | string, required | Concise but complete description: what info to capture, target audience, the offer/value proposition, and any design preferences |
| `language` | string, required | Language code in xx-xx form, e.g. pt-br, en-us |

#### `list_lead_capture_pages` (read)

List all of the customer's lead-capture pages with their generation status and URL.

- `POST /rest/v1/tools/list_lead_capture_pages`
- `GET /rest/v1/call/list_lead_capture_pages`

Parameters: —

### Media

Generate images, drawings and videos, edit a video, and read back everything already generated.

#### `create_video` (write)

Generate a short AI video from a text prompt and an optional first-frame reference image. Renders in the background — this returns immediately with an id; poll list_videos for the finished video_url.

- `POST /rest/v1/tools/create_video`

| Parameters | | |
|---|---|---|
| `prompt` | string, required | The video prompt |
| `model` | string, optional | Engine: SeedancePro, SeedanceProFast (default), Grok |
| `reference_image_url` | string, optional | Optional first-frame image URL (absolute https). The video animates from this image. |
| `duration` | integer, optional | Duration in seconds (clamped per engine) |
| `aspect_ratio` | string, optional | Aspect ratio, e.g. 16:9, 9:16, 1:1, 4:3 |
| `resolution` | string, optional | Resolution: 480p, 720p, or 1080p |

#### `edit_video` (write)

Generate a new video that iterates on a previously generated one. When no reference_image_url is given, the first-frame strategy decides how the starting frame is produced.

- `POST /rest/v1/tools/edit_video`

| Parameters | | |
|---|---|---|
| `video_id` | integer, required | Id of the previously generated video to iterate on |
| `prompt` | string, required | The new video prompt |
| `model` | string, optional | Engine: SeedancePro, SeedanceProFast (default), Grok |
| `reference_image_url` | string, optional | Optional new first-frame image URL (absolute https). Overrides the strategy. |
| `first_frame_strategy` | string, optional | How to handle the first frame: KeepPreviousFirstFrame (default), EditPreviousFirstFrame, GenerateBrandNewFirstFrame |
| `duration` | integer, optional | Duration in seconds (clamped per engine) |
| `aspect_ratio` | string, optional | Aspect ratio, e.g. 16:9, 9:16, 1:1, 4:3 |
| `resolution` | string, optional | Resolution: 480p, 720p, or 1080p |

#### `generate_drawing` (write)

Generate a drawing (shapes, wireframes, page layouts, diagrams, tables, charts, grids, vector shapes, maps). Runs in the background — this returns immediately with an id; poll list_drawings for the finished image_url.

- `POST /rest/v1/tools/generate_drawing`

| Parameters | | |
|---|---|---|
| `prompt` | string, required | Description of the drawing to generate |
| `caption` | string, optional | Optional caption to accompany the delivered image |
| `reference_image_url` | string, optional | Optional absolute https URL of a reference image to send with the prompt |
| `drawing_id` | integer, optional | Optional id of an existing drawing to edit/iterate on |

#### `generate_image` (write)

Generate an image from a text prompt (or edit existing images by passing reference URLs). Generation runs in the background — this returns immediately with an id; poll list_images for the finished image_url.

- `POST /rest/v1/tools/generate_image`

| Parameters | | |
|---|---|---|
| `prompt` | string, required | Prompt describing the image to generate |
| `aspect_ratio` | string, optional | Image format: Square (1:1), Landscape (wider), or Portrait (taller). Default Square. |
| `transparent` | boolean, optional, default `false` | Transparent background (default false) |
| `reference_image_urls` | string, optional | Comma-separated absolute https URLs of reference images to send with the prompt |
| `profile` | string, optional | Optimization profile: None, SocialMediaInstagramPostFeed, SocialMediaInstagramPostStories. Default None. |
| `model` | string, optional | Generation model: OpenAI (default), BytePlus. Don't change unless the user asks. |

#### `get_drawing` (read)

Get one generated drawing by id — the poll target for generate_drawing. Shows the generation status and, once finished, the image_url.

- `POST /rest/v1/tools/get_drawing`
- `GET /rest/v1/call/get_drawing`

| Parameters | | |
|---|---|---|
| `drawing_id` | integer, required | The drawing_id returned by generate_drawing |

#### `get_image` (read)

Get one generated image by id — the poll target for generate_image. Shows the generation status and, once finished, the image_url.

- `POST /rest/v1/tools/get_image`
- `GET /rest/v1/call/get_image`

| Parameters | | |
|---|---|---|
| `image_id` | integer, required | The image_generation_id returned by generate_image |

#### `get_video` (read)

Get one generated video by id — the poll target for create_video/edit_video (list_videos only shows FINISHED videos, so poll this for in-progress ones). is_finished=true with a video_url means done; is_finished=true without a URL means the render failed.

- `POST /rest/v1/tools/get_video`
- `GET /rest/v1/call/get_video`

| Parameters | | |
|---|---|---|
| `video_id` | integer, required | The video_id returned by create_video or edit_video |

#### `list_drawings` (read)

List generated drawings (newest first, paginated). Includes each drawing's generation status and, once finished, its image_url.

- `POST /rest/v1/tools/list_drawings`
- `GET /rest/v1/call/list_drawings`

| Parameters | | |
|---|---|---|
| `page` | integer, optional, default `1` | Page number (1 = first page) |
| `page_size` | integer, optional, default `10` | Page size (default 10, max 50) |

#### `list_images` (read)

List generated images (newest first, paginated). Includes each image's generation status and, once finished, its image_url.

- `POST /rest/v1/tools/list_images`
- `GET /rest/v1/call/list_images`

| Parameters | | |
|---|---|---|
| `page` | integer, optional, default `1` | Page number (1 = first page) |
| `page_size` | integer, optional, default `10` | Page size (default 10, max 50) |

#### `list_videos` (read)

List previously generated videos (newest first, paginated). Only successfully finished videos with a URL are returned.

- `POST /rest/v1/tools/list_videos`
- `GET /rest/v1/call/list_videos`

| Parameters | | |
|---|---|---|
| `page` | integer, optional, default `1` | Page number (1 = first page) |
| `page_size` | integer, optional, default `10` | Page size (default 10, max 50) |

### Online research

Queue a research task on the open web and read the result when it is done.

#### `get_online_search` (read)

Get one online search's status and result.

- `POST /rest/v1/tools/get_online_search`
- `GET /rest/v1/call/get_online_search`

| Parameters | | |
|---|---|---|
| `online_search_id` | integer, required | Id of the online search |

#### `list_online_searches` (read)

List the customer's most recent online searches (up to 10, newest first) with their status.

- `POST /rest/v1/tools/list_online_searches`
- `GET /rest/v1/call/list_online_searches`

Parameters: —

#### `register_online_search` (write)

Register an online research job. It runs in the background — this returns immediately with an id; poll get_online_search for the result. Optionally emails the result when finished.

- `POST /rest/v1/tools/register_online_search`

| Parameters | | |
|---|---|---|
| `query` | string, required | The query to research online |
| `send_to_email` | string, optional | Optional email address(es), comma-separated, to send the result to when finished |
| `type` | string, optional | Search depth: Fast, Standard (default), or Deep |

### Support

The private line to the eesier team — open a request and read the ones already open.

#### `create_support_request` (write)

Open a direct line to the Blue Button support team. This is YOU, the connected agent, talking to the support and engineering team directly — use it to ask a question or report an issue on your own initiative in the background (the end user is NOT notified), or when the user explicitly asks you to contact support. Specify the type (technical, sales, human, or question) and severity (low/medium/high/critical). The team's reply comes back to you — read it later with list_support_requests.

- `POST /rest/v1/tools/create_support_request`

| Parameters | | |
|---|---|---|
| `message` | string, required | What you want to ask or report to the Blue Button team |
| `type` | string, required | Request type: 'technical' (product/technical issue), 'sales' (commercial, billing, plan — the customer wants a sales rep to reach out), 'human' (the customer asks for a human contact, no specific reason), or 'question' (a simple information request you cannot answer yourself) |
| `severity` | string, required | How urgent it is: 'low', 'medium', 'high', or 'critical' |

#### `list_support_requests` (read)

List the customer's support requests — your thread with the Blue Button team — with each request's status, type, severity, and the team's answer (null until they reply). Filter by status: pending, answered, closed, or all (default all).

- `POST /rest/v1/tools/list_support_requests`
- `GET /rest/v1/call/list_support_requests`

| Parameters | | |
|---|---|---|
| `status` | string, optional, default `all` | Status filter: pending, answered, closed, or all (default all) |

### Incidents

Read the platform incidents that affect this account.

#### `list_incidents` (read)

Lists platform incidents (outages / degradations / instabilities) reported by the Blue Button team, each with its public update timeline. Returns ongoing (active) incidents and recently resolved past ones. Call this when the user asks whether the platform is having problems, or when tool calls are failing unexpectedly — an active incident usually explains the failures.

- `POST /rest/v1/tools/list_incidents`
- `GET /rest/v1/call/list_incidents`

| Parameters | | |
|---|---|---|
| `scope` | string, optional | Which incidents to return: 'active' (ongoing only), 'past' (resolved only) or 'all' (default) |
| `limit` | integer, optional | Max past incidents to return (default 10, max 50) |

## Frequently asked questions

**Is this a different product from the MCP server?**

No. It is the same server and the same tools, reached over plain HTTP instead of the MCP protocol. Calls are dispatched into the identical code, so results, limits and logging are identical.

**Do I need an AI agent to use it?**

No. That is the point of this surface. A shell script, a cron job, an n8n or Zapier step, or your own backend can call it with nothing but curl.

**Can I use REST and MCP at the same time?**

Yes, with the same token. Your agent can hold an MCP session while your backend posts to the REST endpoints; both write to the same account.

**What does the HTTP status tell me?**

Exactly what happened: 200 succeeded, 403 means your plan does not include that tool, 404 means the tool or the object does not exist, 422 means the tool refused the request, 500 is a permanent fault and 503 is a transient one worth retrying. The body always carries the machine-readable reason.

**Is there a rate limit?**

There is no per-endpoint rate limit. Some write tools require an active plan and say so in a clear message instead of failing silently.

**How do I keep up with new tools?**

GET /rest/v1/tools is generated from the running server, so new tools appear the moment they ship. This page is generated from the same registry.