@kaminari-ad/mcp

Update an alert's status in its lifecycle: open → escalated → resolved | dismissed. The API enforces valid transitions; an invalid one returns 422.

Restore an archived campaign. Inverse of `archive_campaign`. The campaign re-appears in default lists; if `schedule_enabled` was true, the scheduler resumes producing runs.

Get alert counts grouped by status: open, escalated, resolved, dismissed. Counts cover the caller's organization over all time and are not filtered, so the four sum to the `total` an unfiltered `list_alerts` reports. Status names match the canonical AlertStatus enum used by `list_alerts` and `update_alert_status`.

List violation alerts (one per scan + violating rule combo) with offer URL, country, status, scan back-reference, and the kind-aware fields `rule_type` (tag / iab_v3 / brand / ai_category / custom_taxonomy) + `matched_value` (the canonical text the scan matched against).

List the roles defined for the organization — built-in (owner, admin, member) plus any custom roles, with each role's permission set.

Update the caller's organization display name.

Create a custom organization role with the supplied permission set. Returns the persisted role; assign it to users via `update_user_role`.

Hand the organization owner role to another existing member. ONE-WAY: the previous owner becomes a regular member afterwards. Require explicit confirmation from the user.

Get the organization owning the current API key (id, name, owner_id, is_active, created_at). Use this to confirm authentication and capture the org context for follow-up tool calls.

List every member of the caller's organization with their role, ownership flag, and join date.

List the organization's API keys: id, key prefix (first 8 chars of the secret), display name, expiry, created_at. The full secret is NEVER returned by this endpoint — only the prefix.

Permanently invalidate an API key. Any subsequent request using it returns 401. Cannot be undone — the user would have to `create_api_key` again.

Mint a new API key for the caller's organization. The full secret is returned in `full_key` THIS ONE TIME ONLY — show it to the user and instruct them to store it; the server keeps only a hash and cannot reveal it again.

List the organization's custom label definitions (key, display_name, position, auto_extract). Labels enrich scans and can be used as filters in `list_scans`.

Change an organization member's role. The owner role can only be transferred via `transfer_ownership`. Returns `{updated: true}` on success; refetch with `list_org_users` if you need the new role echoed.

Revoke a member's access to the organization. The user is signed out and any active API keys they created remain unless revoked separately. CANNOT remove the owner — use `transfer_ownership` first.

REPLACE the organization's full set of custom label definitions. The API replaces the list (no merge); read the current list with `list_account_labels` first. Returns the persisted list with allocated positions.

Send an invitation email so a new person can join the caller's organization with a chosen role. Returns the pending member record.

List campaigns for the caller's organization, optionally filtered by group, archived flag, or name substring. Paginated. Each row carries the same fields as `get_campaign`, including the repeat / retry settings (`repeat_count`, `repeat_mode`, `retry_max_attempts`) — use them to spot the campaigns that multiply their per-run scan count.

Update one or more fields of a campaign. Fields not supplied are left unchanged. `policy_set_id` accepts null to clear the binding, and `referrer` accepts null to clear the publisher page scans are checked from.

Trigger an immediate, ad-hoc run of a campaign. Costs N credits where N = number of countries × number of emulators in the campaign config. Returns the new run with progress counters (total / completed / failed / partial / cancelled); track further progress via `get_run`.

List every run (scheduled execution) of one campaign, paginated, with per-run counters.

Slim per-row campaign list for selection UIs — id, name, group_id, is_archived. Cheaper than `list_campaigns` for orgs with thousands of campaigns. Use `get_campaign(id)` after a selection to fetch full details.

Create a recurring scan campaign (template). The schedule produces N scans per run where N = number of countries times number of device profiles times `repeat_count`. Scans cost credits when they run, not when the campaign is created, so a high `repeat_count` multiplies the bill on every run. The returned campaign echoes `repeat_count`, `repeat_mode`, and `retry_max_attempts`, so read it back to confirm what the campaign will do.

Cancel every pending scan across all unfinished runs of a campaign. Running scans complete normally; pending scans are marked cancelled and credits refunded. Returns count of cancelled scans.

Get one campaign by UUID: name, type (url|ad_tag|vast|ad_discovery), target URL / ad-tag / VAST tag (vast_tag), countries, emulator selection, proxy targeting, schedule status, archive status, parent group. Also echoes the repeat / retry settings — `repeat_count`, `repeat_mode`, `retry_max_attempts` — so this is how you confirm what `create_campaign` or `update_campaign` actually saved, and how many scans a run will produce (countries x device profiles x `repeat_count`). `ad_discovery` campaigns store the publisher page in the URL field.

Soft-delete (archive) a campaign. Removes it from default lists and stops the scheduler; previously-collected scans are preserved.

Get one policy set by UUID with its complete list of entries (each entry is one of five rule kinds — tag / iab_v3 / brand / ai_category / custom_taxonomy — plus applicable country codes).

Paginated list of policy sets: named collections of violation rules (tag / IAB V3 / brand / AI category / custom-taxonomy entries) that define what counts as a violation. Campaigns bind to one policy set. Returns `{items, total, page, limit}`. List items omit `entries` for payload size — fetch a single set via `get_policy_set` when you need them. Use `visibility=public` to discover Kaminari Ad-curated sets.

Create a new policy set (named collection of violation rules). Each rule is one of: tag slug, IAB V3 category prefix, advertiser brand, freeform AI category, or per-org custom-taxonomy node. Bind campaigns to the set via `update_campaign`.

REPLACE a policy set's name, description, and entry list. The API requires all three fields on every update — read the current set with `get_policy_set` first if you only want to change one thing. Supports all five rule kinds (tag / iab_v3 / brand / ai_category / custom_taxonomy).

Permanently delete a policy set. IMPORTANT: API returns HTTP 400 if any active campaign is still bound to this set. To unbind first, call `list_campaigns` with a `policy_set_id` filter (when available) or scan your campaigns for matches, then `update_campaign` for each match setting `policy_set_id=null`, then retry delete. Alerts created under this set persist (their `policy_set_id` becomes `null`).

Submit a private policy set for Kaminari Ad team review so it can be marked PUBLIC and used by other organizations. The set must be complete and well-formed. Returns immediately; approval status is reflected on the policy set entity once the review completes.

Fire an immediate run of every active (non-archived, non-paused) campaign in the group. Returns aggregate stats: how many campaigns triggered, the per-campaign run UUIDs, and any per-campaign failures.

Get one campaign group by UUID with default/archive/pause flags and campaign count.

Create a new campaign group (folder). Free operation, no scans queued.

Pause the scheduler for EVERY campaign in the group. Already-pending scans complete; no new scheduled runs are produced until you `resume_campaign_group_schedule`.

Restore an archived campaign group and re-expose its campaigns in default lists.

Cancel every pending scan across every campaign in the group. Refunds credits for cancelled scans. Returns the total cancelled count.

Rename a campaign group. To pause/resume its scheduler, use `pause_campaign_group_schedule` / `resume_campaign_group_schedule` instead.

Re-enable the scheduler for every campaign in the group. Inverse of `pause_campaign_group_schedule`.

Soft-delete the group AND every campaign in it. The default group cannot be archived; ask the user to move campaigns out first.

List campaign groups — folders that group related campaigns. Includes per-group campaign count. Not paginated; the org-scoped list is typically small (a few dozen groups max).

List ledger transactions (charges, refunds, top-ups, invoice settlements) on the organization's balance. Each row: type, amount in micros, description, timestamp. Filter by `type` (multi-select) and / or date range.

List per-scan usage rows (cost in micros, kind, scan id, timestamp). Use to attribute cost to specific scans or campaigns.

Get a one-liner aggregate of usage for the current billing period: total cost (micros), check count, period start/end.

Get the organization's billing snapshot: balance (in micros), current plan, period usage counters, suspension state, and whether new scans are accepted right now.

Cancel one pending scan by UUID. Already-running or completed scans are no-ops. Cancellation refunds the scan credit.

List every device/OS emulator profile available for scans (id, display name, category, browser). For `create_scan`, use the `id` as `emulator_id`. For `create_campaign` / `update_campaign`, use the `category` in `emulator_categories` or the `id` in `emulator_specific_ids`.

Get one custom taxonomy by UUID with its full node tree (each node has id, parent_id, level, position, name, description, is_default).

Re-activate a previously soft-deleted custom taxonomy. Returns the restored taxonomy with its full tree (is_active=true).

Create a custom classification taxonomy with its initial tree. Exactly one node should have is_default=true (fallback for scans the LLM cannot classify confidently). Returns the persisted taxonomy with allocated node UUIDs and version=1.

REPLACE a custom taxonomy's name, description, and full tree atomically. The API bumps `version` on every successful update; ongoing scan classifications continue with the previous tree until they finish, so updates are safe but not retroactive.

List the calling org's custom classification taxonomies. Returns slim summaries (id, name, slug, version, node_count, is_active). Soft-deleted taxonomies are included with `is_active=false`. Fetch the full tree via `get_custom_taxonomy`.

Soft-delete a custom taxonomy (sets is_active=false). Historical scan classifications keep referencing the id; new scans skip this taxonomy. Use `restore_custom_taxonomy` to undo.

Preview-parse pasted free-form text into a taxonomy tree (NOT persisted). Returns `nodes: [{level, name, description}]` + `warnings: string[]`. After review, persist via `create_custom_taxonomy` (remember to flag exactly one node as is_default).

List invoices issued to the organization with number, type, status, total in micros, currency, due/paid dates. Filter by `type` and / or `status`. Use `get_invoice_pdf` to download the PDF for a specific invoice.

Download one invoice as an inline PDF (base64-encoded). Returned as a single MCP resource content block — agents can save / forward it without a second API call.

List scans for the caller's organization with optional filters (status, country, URL substring, date range, run/campaign/group, tag, AI/IAB/brand category, dynamic labels). Returns a paginated envelope; each brief carries `is_ad_tag` and `is_vast` flags, an absolute screenshot URL plus report_url (auth dashboard) and public_report_url (shareable) deep-links — link users with those, never hand-build URLs. Repeated scans look like near-duplicate rows: `repeat_index` / `repeat_total` place each one inside its repeat group (0-based) and a non-null `repeat_session_id` means the group ran in `shared` mode (one browser, one IP, cookies carried across repeats) — group by it to compare the repeats of one combination. `retry_attempt` / `retry_max_attempts` count technical re-crawls of that same scan, not extra scans. `repeat_scan_ids` is not part of this response; use `get_scan` for a single scan's full detail.

List the discovered-ad child scans of a publisher ad-discovery scan — one per detected ad block on the page. Each child brief carries ad_kind (banner|pop), the attributed ad network, and slot_index. The repeat / retry fields are present but never meaningful here: a child is always its own group of one (`repeat_index` 0, `repeat_total` 1, `repeat_session_id` null) and is never re-crawled, because repeats and retries apply to the publisher scan — repeating an ad-discovery scan gives you several parents, each with its own children. Returns a paginated envelope with screenshot + report deep-links; link users with those, never hand-build URLs.

Queue a single new scan for a URL, ad-tag, or VAST video tag against one country. Takes one target and one country — there is no multi-URL form; call it once per URL. COSTS CREDITS and bills the caller's organization: this call creates exactly `repeat_count` scans (default 1) and bills every one of them. Returns the newly-created scan record; when `repeat_count` > 1 the response's `repeat_scan_ids` lists the sibling scans this call also created.

Queue one new scan per country in a single call (e.g. test the same URL, ad-tag, or VAST video tag from US + DE + JP). COSTS N CREDITS where N = number of countries times `repeat_count`. Returns one entry per country; each entry's `repeat_scan_ids` lists that country's extra repeats.

Get full detail for one scan by UUID: status, offer URL, absolute screenshot URL, report_url + public_report_url deep-links, timing, labels, and the parent campaign if any. VAST video scans also carry `vast_tag`, `creative_kind` (`banner` or `video` today; treat it as an open string), and a `video` block (duration, media-file URL, the creative's `click_through` destination, VAST version, ad system, VPAID flag, wrapper depth). Repeats and retries: `repeat_index` / `repeat_total` place this scan inside its repeat group (0-based, so 2 of 5 reads as repeat_index 1), a non-null `repeat_session_id` means the group ran in `shared` mode (same browser, same IP, cookies carried over) and is the key to correlate its members — a shared group of one has nothing to carry over, so it stays null — `repeat_scan_ids` is filled only on the create response, and `retry_attempt` / `retry_max_attempts` show how many technical re-crawls this scan already consumed. Link users with the returned `report_url` / `public_report_url` — never construct URLs yourself.

Fetch the creative screenshot for an ad-tag scan as an inline image (base64-encoded PNG). Returns 404 if the scan is not an ad-tag scan or has no creative captured yet.

Fetch the screenshot of one landing tab on an ad-tag scan as an inline image. Use `get_scan` first to discover available `landings[*].ord` values.

Re-run the checker pipeline against recent COMPLETED scans (e.g. after updating policies or custom rules). Returns the number of scans queued for re-evaluation. No new crawl fee — only the checker cost.

Fetch the primary screenshot for a scan as an inline image (base64-encoded PNG). Pass `width` to request a resized version (50-2000 px). Returns one MCP image content block.

Update display fields of a CUSTOM tag (system tags are read-only). Only supplied fields are touched. To read the updated definition, follow up with `get_tag_definition`.

List every tag (system + custom) attached to one scan by the checker pipeline, with display name, category, and severity.

List every tag definition the platform knows (system tags + organization custom tags) with category, severity, visibility, and usage counters (scans + rules per tag). Optionally filter by category.

Get full definition of one tag: display name, description, severity, category, source (system vs custom), public-report visibility, usage counts, plus `linked_rules` — the custom rules currently producing this tag (id, name, active flag). Fetch a specific rule's full config via `get_custom_rule`.

Delete a CUSTOM tag definition. Historical tag assignments are preserved; future scans will not receive this tag. System tags cannot be deleted.

Preview-test a rule definition against a stored scan without persisting it. For `regexp_request_url`, the historical snapshot contains main-frame hops plus at most 200 persisted subrequests with selected resource types omitted, so a no-match does not prove the original fresh scan lacked the request. Returns match state, elapsed time, and per-tag detail; the preview response does not expose the matched request URL separately. Slug-collision validation does not run in preview mode.

Paginated list of the organization's custom tag-detection rules (regex / heuristics) with their config, target, and active flag. Returns `{items, total, page, limit}`. To iterate: there is a next page iff `page * limit < total` (or equivalently `items.length === limit` until the last page). `page` is 1-indexed.

Get one custom rule by UUID with name, tag-slug, type, config object, target, active flag.

Define a custom tag-detection rule. Use `rule_type='regexp_request_url'` to match captured network and subresource URLs on the fixed `page` target; fresh scans carry up to 5,000 URLs, while later tests/rechecks use a reduced persisted request tree and are best-effort. `rule_type='regexp_url'` remains redirect-chain-only. The API auto-registers a tag definition for each emitted slug and rejects built-in system-slug collisions with HTTP 422 / `checking.system_slug_reserved`. Matches tag future scans; existing scans are untouched until `recheck_scans`.

Update a custom tag-detection rule. Only supplied fields are sent, but `config` replaces the stored object wholesale; read the rule first and resend every required key. `regexp_request_url` needs a non-empty pattern (max 4,096), flags `''`/`'i'`, and the fixed `page` target. Same-slug GLOBAL rule edits preserve separately managed tag metadata; use `update_tag_definition` to change it. Existing scans are not re-evaluated until `recheck_scans`.

Permanently delete a custom rule. Already-applied tags on past scans are preserved; the rule simply stops running on future scans.

Unregister a webhook endpoint. No further events are delivered; in-flight retries are dropped. Past delivery history is preserved.

Get one webhook endpoint by UUID with URL, subscribed event types, active flag.

List the catalog of event types a webhook can subscribe to (e.g. `scan.done`, `alert.opened`, `campaign.run.completed`) with each event's description and a sample payload.

Queue a re-attempt for one specific webhook-delivery attempt by id. Useful when an endpoint was temporarily down. Result of the replay shows up as a new entry in `list_webhook_deliveries`.

Register a webhook endpoint for the chosen event types. Response is a `{ webhook, secret }` envelope — the HMAC-SHA256 SIGNING SECRET is returned once and the caller MUST store it to verify event signatures.

Update a webhook endpoint's URL, event-type subscriptions, and/or active flag. Signing secret is NOT rotated by this call — use `rotate_webhook_secret` for that.

List the organization's registered webhook endpoints with their URL, subscribed event types, and active flag.

Generate a new signing secret for a webhook. The new secret is returned IN FULL once — tell the user to store it. Subsequent deliveries are signed with the new secret; the old one stops working immediately.

Dispatch a synthetic event with the sample payload for the given `event_type` to the webhook endpoint and return the receiver's response synchronously. Includes HTTP status, elapsed time, and a snippet of the response body so the operator can diagnose receiver bugs.

Replay every delivery attempt for this webhook endpoint that landed in [from_ts, to_ts). Returns `{ replayed, skipped }` counts. Use to recover after a downstream outage — every event in the window is re-fired.

List delivery attempts for one webhook endpoint with event type, status (pending / delivered / failed), HTTP response status if any, and attempt timestamp. Filter by `success` and / or a `from_ts` / `to_ts` range. Paginated.

List the tile-scan items produced by one run (status, country, offer URL, absolute screenshot URL, report_url + public_report_url deep-links, elapsed ms, error). Link users to a scan with the returned `report_url` (auth dashboard) or `public_report_url` (shareable) — never hand-build URLs. For full scan details (input URL, labels, classification, redirect chain) fetch a specific scan via `get_scan`.

Cancel every pending scan within one run. Running scans complete; pending ones get refunded. Returns the count of cancelled scans.

Get one run by UUID with totals (queued, completed, failed, partial, cancelled), parent campaign, label, source.

Remove an alert-notification destination. The org stops receiving pings on this channel immediately; campaign-level overrides referencing it are pruned.

Get the per-campaign override of which alert destinations receive its alerts. `mode` is one of `inherit` (use org defaults), `include` (use the listed destinations), or `exclude` (use everything EXCEPT the listed destinations).

Switch a destination to a specific versioned config — used after re-authorizing a Slack workspace, rotating a Telegram bot token, etc. The new version must already exist in the destination's history. The API returns no body on success; this tool reports `{ updated: true }`. Use `list_alert_destinations` to read the new state if needed.

List configured alert-notification destinations (channels): Slack workspaces, Telegram chats, email lists, generic webhooks. Each entry has id, kind, display name, version, and creation timestamp.

REPLACE the per-campaign alert-routing override. `mode=inherit` falls back to org defaults; `mode=include` routes ONLY to the listed destinations; `mode=exclude` routes everywhere EXCEPT the listed destinations. To read the new state, follow up with `get_campaign_alert_overrides`.

List every country the Kaminari Ad platform can scan ads from, with ISO 3166-1 alpha-2 code, name, continent, and emoji.