Skip to content
GridRouterhome

Search

Search providers, capabilities and pages

Docs

MCP server

Every GridRouter operation as an MCP tool, plus catalog resources, a live log subscription and prompts.

Before you start

https://mcp.gridrouter.io/mcp serves the same operations as the REST API. Each tool is one operation: the same input schema, the same result, the same errors. Tools a connection's scopes do not cover are not listed; public tools such as catalog_search are always listed.

Every tool result includes the call's cost in _meta["io.relaygrid/cost_micro"]. A failed call returns isError: true with code: message text and the error body as structured content.

Resources

URIWhat
grid://catalog/endpoints/{provider}/{endpoint}One endpoint's definition, pricing and quality
grid://catalog/capabilitiesEvery capability and the endpoints that serve it
logs://liveThe newest calls, waterfall steps, jobs, lists and alerts; subscribable. Filter with a query: logs://live?capability=people.email.find&status=error (logs:read)
grid://jobs/{id}Status and result of a job (jobs)
grid://lists/{id}Progress of a list run (lists)

Tools that start a job or list return a resource_link to its grid:// URI.

Prompts

  • find_verified_email (first_name, last_name, domain): runs people.email.find, then email.verify on the result, and reports the total cost.
  • research_account (domain, budget_usd, default 0.50): quotes each call and keeps the research under budget.

Waterfall templates

An agent can go from a goal to a running waterfall with four tools:

  1. waterfall_templates (public) lists the templates with availability.status, the vendor keys that unlock each one and its cost range. waterfall_template_get shows one template's inputs, outputs and step-by-step explanations.
  2. waterfall_estimate with {"template":"work-email"} prices it without calling a provider.
  3. waterfall_create_from_template copies it into the workspace and publishes it (pipelines:write), with optional pins, speed and max_cost_micro.
  4. waterfall_run with {"id":"wf_…","input":{…}} returns the golden record. With "async": true, it returns a run id to poll with waterfall_status.

See waterfall templates. The public gridrouter-waterfalls skill walks an agent through it.

Tools

The same list is available as JSON from GET https://api.gridrouter.io/v1/tools?format=mcp (or openai / anthropic for function-calling schemas).

Tool, REST route and scopeDescription
catalog_search
GET /v1/catalog/endpoints
public
Find vendor endpoints by keyword (capability, vendor, what they return). Returns price and quality.
catalog_get
GET /v1/catalog/endpoints/{provider}/{endpoint}
public
Full definition of one endpoint: input JSON Schema, pricing model and quality.
vendor_search
GET /v1/catalog/vendors
public
Every GTM data vendor GridRouter knows about (integrated or researched): API access, spec status, published rate limits and marketplace listings.
vendor_get
GET /v1/catalog/vendors/{slug}
public
One vendor's sourced record: company, API surface, docs, pricing, data, compliance, relationships and marketplace listings, each with sources and confidence.
vendor_openapi
GET /v1/catalog/vendors/{slug}/openapi
public
The stored OpenAPI document for a vendor: the vendor's official spec, or one GridRouter reconstructed from its docs (x-reconstructed, x-confidence, x-source-url on every operation).
vendor_rate_limits
GET /v1/catalog/vendors/{slug}/rate-limits
public
Published rate limits (per window, concurrency, headers, 429 behaviour) with source and check date, and the pacing GridRouter derives from them.
capabilities_list
GET /v1/catalog/capabilities
public
Capabilities (normalized tasks like people.email.find) and the endpoints that serve each.
categories_list
GET /v1/catalog/categories
public
Top-level GTM data categories.
leaderboard_get
GET /v1/catalog/leaderboards/{capability}
public
Endpoints for a capability ranked by usage-derived quality (Wilson lower bound).
quote
POST /v1/quote/{provider}/{endpoint}
call
Worst-case cost of calling an endpoint with this input, without calling it.
call
POST /v1/call/{provider}/{endpoint}
call
Call one vendor endpoint. Reserves the worst-case cost, charges the actual cost. Async vendors return a job. Runs as an MCP task.
run_auto
POST /v1/run/auto
run
Auto router: GridRouter picks the capability from the input fields you have (and the output fields you ask for), then routes it like run. The chosen capability and the alternatives are returned.
run
POST /v1/run/{capability}
run
Routed call: GridRouter picks vendors (waterfall/cheapest/best) until one hits. Only hits are charged on per-success vendors.
call_get
GET /v1/calls/{id}
call
Cost, timings (total, upstream, overhead, TTFB, queue), provider, outcome and every routed attempt of one call, like OpenRouter's generation lookup. Keys without logs:read only see calls they made. Available a few seconds after the call.
presets_list
GET /v1/presets
catalog:read
Saved routing presets for this org: provider preferences, field selection, max cost and stop rule. Use one as preset: "@slug" on run.
presets_get
GET /v1/presets/{slug}
catalog:read
One saved routing preset.
presets_create
POST /v1/presets
presets:write
Create or replace a routing preset shared within the org (order/only/ignore/sort/max price/data policy, credential, fields, max cost, stop rule).
presets_delete
DELETE /v1/presets/{slug}
presets:write
Delete a preset. Requests that name it fail with not_found afterwards.
job_create
POST /v1/jobs
jobs
Run any endpoint in the background through the job queue, with per-vendor pacing. Runs as an MCP task.
job_get
GET /v1/jobs/{id}
jobs
Status and result of a queued or async job.
list_create
POST /v1/lists
lists
Run an endpoint or capability over up to 10,000 rows in the background. Runs as an MCP task.
list_get
GET /v1/lists/{id}
lists
Progress and cost of a list run.
list_rows
GET /v1/lists/{id}/rows
lists
One page of per-row results for a list.
balance_get
GET /v1/balance
balance:read
Prepaid balance, amount held for in-flight calls, and what is available.
budget_set
PUT /v1/budgets
keys:write
Cap spend for the org, one key, or one agent per day, month or total.
budgets_list
GET /v1/budgets
balance:read
Every spend cap (workspace, key, agent) with its period and what it used in the current window.
budget_remove
DELETE /v1/budgets
keys:write
Remove the spend cap for the org, one key, or one agent.
keys_list
GET /v1/keys
keys:write
API keys for this org (never the secret).
keys_create
POST /v1/keys
keys:write
Mint a scoped key. The secret is returned once.
keys_revoke
DELETE /v1/keys/{id}
keys:write
Revoke a key. Billable calls stop immediately.
recovery_codes_create
POST /v1/recovery-codes
keys:write
Owner only (a * key): issue 10 one-time recovery codes that can mint a new owner key if every key is lost. Replaces earlier codes; shown once.
keys_rotate
POST /v1/keys/{id}/rotate
keys:write
Mint a replacement key with the same scopes and limits; the old key keeps working for grace_seconds (default 24 h), then expires.
keys_limit_set
PUT /v1/keys/{id}/limit
keys:write
Cap what one key can spend, resetting daily, weekly, monthly or never. null removes the cap. Calls over the cap fail with budget_blocked.
agents_create
POST /v1/agents
agents:write
Create an agent with its own budget and mint an agent key for it.
log_views_list
GET /v1/logs/views
logs:read
Your saved log views plus views shared with the workspace, newest first. A view is a query in the log query language and the visible columns.
log_views_create
POST /v1/logs/views
logs:read
Save the query and visible columns under a name. shared: true (owners and admins only) makes it visible to the whole workspace; replace: true overwrites your view with the same name.
log_views_update
PUT /v1/logs/views/{id}
logs:read
Rename a view or change its query, columns or sharing. You can change your own views; owners and admins can also change shared ones.
log_views_delete
DELETE /v1/logs/views/{id}
logs:read
Delete one of your views (owners and admins can also delete shared views).
log_views_import
POST /v1/logs/views/import
logs:read
One-time move of views and pins the dashboard kept in the browser. Views whose names you already use and calls already pinned are skipped.
log_pins_list
GET /v1/logs/pins
logs:read
Calls you pinned to the top of the log viewer, newest pin first, each with its current log row (null once the call is past log retention).
log_pins_create
POST /v1/logs/pins
logs:read
Pin a call to the top of the log viewer. You keep up to 20 pins; the oldest drops off.
log_pins_delete
DELETE /v1/logs/pins/{call_id}
logs:read
Remove a pinned call.
logs_list
GET /v1/logs
logs:read
Every call and routed attempt for this org, newest first (360-day retention). Filter by time, outcome, status, provider, capability, endpoint, key, agent, client, mode, credential, error code, latency and cost; cursor-paginated.
logs_facets
GET /v1/logs/facets
logs:read
Counts per value (outcome, status, provider, capability, endpoint, key, client…) and latency/cost ranges for the same filters as logs_list.
logs_stats
GET /v1/logs/stats
logs:read
Calls, error rate, p50/p95/p99 latency, spend, a hit/miss/failed timeline and spend by provider over time, for the same filters as logs_list.
logs_billing
GET /v1/logs/billing
logs:read
Per vendor, how many of your own-key (BYOK) calls were billed as the vendor's published rule says, how many were charged for a miss, double-charged on a retry or at the wrong price, and the credits and dollars at stake. Same filters as logs_list.
logs_get
GET /v1/logs/{id}
logs:read
One call with timings, its redacted request/response body (audit-logged), the other attempts in its routed run or list, and its ledger entries.
settings_get
GET /v1/settings
logs:read
Org data settings, such as whether request/response bodies are stored.
settings_update
PUT /v1/settings
keys:write
Turn body storage on or off (off stops new bodies from being kept) and set how many days of call log members and keys can read (30, 90, 180 or 360).
credentials_list
GET /v1/credentials
credentials:write
Your own vendor keys (BYOK) stored for this org: provider, slot, label, field names, the key's last four characters and its last test result. Secrets are write-only and never returned.
credentials_put
PUT /v1/credentials/{provider}
credentials:write
Store your own key for a provider as the primary or fallback slot, envelope-encrypted. BYOK calls are never charged by GridRouter.
credentials_remove
DELETE /v1/credentials/{provider}
credentials:write
Delete one slot of your own key for a provider. Calls fall back to the next slot.
credentials_test
POST /v1/credentials/{provider}/test
credentials:write
Call the provider's free, read-only test endpoint (for example a credit balance) with your stored key. Never charged; the call is logged.
credentials_verify
POST /v1/credentials/{provider}/verify
credentials:write
Call the provider's free, read-only test endpoint with a key that is not stored yet. Nothing is saved; the key is used for this one call. Never charged; the call is logged.
credentials_update
PUT /v1/credentials/{provider}/label
credentials:write
Set or clear the label of a stored key. The secret is not touched.
credentials_swap
POST /v1/credentials/{provider}/swap
credentials:write
Make the fallback key the primary and the primary the fallback for one provider. Takes effect on the next call.
apps_list
GET /v1/apps
logs:read
Apps attributed on your calls (X-Grid-App, or HTTP-Referer + X-Title like OpenRouter) with 30-day usage, plus how each is listed.
apps_put
PUT /v1/apps/{id}
keys:write
Name an attributed app and opt it in (or out) of the public rankings and showcase. A domain-style id must match its URL; another org's public id is refused.
auth_code_create
POST /v1/auth/codes
keys:write
Consent step of Sign in with GridRouter (OAuth PKCE, S256): a signed-in member approves an app and gets a one-time code (10 minutes) to redirect back with.
auth_keys_exchange
POST /v1/auth/keys
public
Final step of Sign in with GridRouter: exchange the one-time code and its PKCE code_verifier for a user-controlled key with call/run scopes and any credit limit the user set.
rankings_get
GET /v1/rankings
public
Top capabilities, providers, categories and opted-in apps by calls and hits over the last day, week or month across all GridRouter traffic, with change vs the previous window and trending movers.
apps_directory
GET /v1/catalog/apps
public
Public apps built on GridRouter (owners opted in), ranked by calls with their top capabilities and providers.
app_profile_get
GET /v1/catalog/apps/{id}
public
One public app: 30-day usage by day, top capabilities and providers.
activity_get
GET /v1/catalog/activity
public
Per-endpoint uptime (share of calls without a vendor-side failure), p50/p95 latency and volume over time for a capability or provider, plus the top public apps using it.
status_get
GET /v1/status
public
Live health per provider: vendor failures in the last 30 seconds (the router's outage signal), last-hour error rate and latency, and 24-hour and 30-day uptime with daily bars.
tools_export
GET /v1/tools
public
Endpoint and capability tools in OpenAI, Anthropic or MCP format.
registry_validate
POST /v1/registry/validate
public
Lint a provider + endpoints YAML submission against the registry schema and margin guard.
usage_by_tag
GET /v1/usage
balance:read
Spend and calls grouped by a meta tag over a window (reads the Postgres mirror). (planned: not yet available)
registry_submit
POST /v1/registry/submissions
keys:write
Submit catalog YAML (validated as in registry_validate) for review by the GridRouter team.
announcements_list
GET /v1/announcements
public
Current platform announcements (maintenance windows, incidents, launches).
review_create
POST /v1/reviews/{provider}/{endpoint}
call
Leave a rating backed by your verified call count. (planned: not yet available)
waterfall_catalog
GET /v1/waterfalls/catalog
pipelines:read
Every capability with its inputs, normalized output fields, and the endpoints a waterfall can use: price, quality, fill, p50 and rate limits.
waterfall_templates
GET /v1/waterfalls/templates
public
Prebuilt GTM waterfalls (work email, mobile, verification, catch-all, person and company enrichment, job change, full lead enrichment, CRM hygiene and more). Each item has its inputs, outputs, sample_input, recommended speed and run_mode, the explained steps, and availability computed from the catalog: status (ready = runnable now, sandbox = runs on a test key, needs_integration = preview only), vendor_keys (add any one per stage in Settings > Vendor keys) and a list-price cost range in micro-USD. future lists recipes that aren't buildable yet and why. Public: no key needed.
waterfall_template_get
GET /v1/waterfalls/templates/{template_id}
public
One template by id (or an earlier id): its definition, inputs and outputs, sample_input, explained steps and catalog availability (status, vendor_keys, cost range). Public: no key needed.
waterfall_create_from_template
POST /v1/waterfalls/from-template
pipelines:write
Copy a template into your workspace in one call, optionally pinning vendors per stage, overriding speed or capping cost, and publish it (default) so waterfall_run works right away. Returns the waterfall (id, name, endpoint). Templates with status needs_integration are rejected with validation_failed. Next: waterfall_run with {id, input}.
waterfall_list
GET /v1/waterfalls
pipelines:read
Waterfalls and pipelines in this org, newest first, with their published version.
waterfall_create
POST /v1/waterfalls
pipelines:write
Create a draft waterfall (one capability, ordered vendor steps, speed profile, stop rules, per-field merge) or a multi-stage pipeline. Start from a definition, a template or a routing preset.
waterfall_get
GET /v1/waterfalls/{id}
pipelines:read
One waterfall: its draft definition, versions and published endpoint.
waterfall_update
PUT /v1/waterfalls/{id}
pipelines:write
Replace the draft definition, title or description. Published versions never change.
waterfall_delete
DELETE /v1/waterfalls/{id}
pipelines:write
Delete a waterfall and its versions; its published endpoint stops answering.
waterfall_estimate
POST /v1/waterfalls/estimate
pipelines:read
Price a waterfall before running it, without calling any vendor: per-step quote, p50 latency, fill and reach, plus worst-case and expected cost (micro-USD) and ETA. Pass a definition, or a template id with the same pins/speed/max_cost_micro choices as waterfall_create_from_template.
waterfall_versions
GET /v1/waterfalls/{id}/versions
pipelines:read
Every published version (immutable), newest first.
waterfall_publish
POST /v1/waterfalls/{id}/versions
pipelines:write
Freeze the draft as a new semver version and serve it at /v1/x/{workspace}/{name} (REST, MCP x_run and OpenAPI).
waterfall_rollback
POST /v1/waterfalls/{id}/rollback
pipelines:write
Serve an earlier published version again. Nothing is deleted.
waterfall_preset
GET /v1/waterfalls/{id}/preset
pipelines:read
The waterfall's vendor order as a routing preset body for presets_create, so /v1/run can use it as @slug.
waterfall_openapi
GET /v1/waterfalls/{id}/openapi
pipelines:read
OpenAPI 3.1 for the waterfall's published endpoint /v1/x/{workspace}/{name}.
waterfall_run
POST /v1/waterfalls/{id}/run
pipelines:run
Run a waterfall on one input and get the golden record: data, _provenance per field (vendor, confidence, verified, conflicts), _attempts, outcome (hit, partial, miss, failed) and cost_micro. Sync by default (up to 50 s). wait: N seconds falls back to a queued run; async: true returns at once with status queued and the run id: poll waterfall_status with {id, run_id}. version defaults to published; use draft for an unpublished waterfall. Set max_cost_micro to cap spend. A vendor you have no key for is skipped; when none can run, the error is vendor_key_required naming them. For lists use waterfall_batch_run.
waterfall_batch_run
POST /v1/waterfalls/batch-run
pipelines:run
Run a waterfall over up to 1,000 inputs (JSON rows or CSV) in the background through gr-rows, paced per vendor. Returns the batch (a list) to poll. Runs as an MCP task.
waterfall_runs
GET /v1/waterfalls/{id}/runs
pipelines:read
Recent runs of one waterfall: outcome, cost, time, attempts and fields filled.
waterfall_status
GET /v1/waterfalls/{id}/runs/{run_id}
pipelines:read
Poll a run started with async or wait: status (queued, running, completed, failed, cancelled), then the golden record with _provenance per field, every attempt with its timing and error, and cost per filled field.
waterfall_run_events
GET /v1/waterfalls/{id}/runs/{run_id}/events.json
pipelines:read
Progress events of a run after a sequence number (the SSE stream's JSON form).
waterfall_cancel
POST /v1/waterfalls/{id}/runs/{run_id}/cancel
pipelines:run
Stop a queued or running run. In-flight attempts are aborted and released; the partial result is kept.
x_run
POST /v1/x/{workspace}/{name}
pipelines:run
Call your own published waterfall by name: /v1/x/{workspace}/{name}, where workspace is your org id. Same modes as waterfall_run.
plans_list
GET /v1/plans
public
Every GridRouter plan with its price, limits, features and managed-call markup, plus the shared overage rates and always-free list.
entitlements_get
GET /v1/entitlements
balance:read
This org's plan, resolved limits (null means no cap), features and usage this month, including logged calls and overage blocks.
billing_get
GET /v1/billing
balance:read
Billing mode, plan and subscription status, balance (with any simulated test credit), auto-recharge and receipts.
billing_checkout_create
POST /v1/billing/checkout
billing:write
Buy credits (amount_usd, the 5.5% top-up fee is added) or upgrade to a paid plan. Returns a URL: Stripe Checkout, or the test purchase page when billing is simulated.
billing_checkout_get
GET /v1/billing/checkout/{id}
balance:read
One checkout session and its status (open, completed, declined, requires_action).
billing_checkout_complete
POST /v1/billing/checkout/{id}/complete
billing:write
Simulated billing only: approve, decline or require card action on a test checkout. Emits the same events Stripe would; no card is charged.
billing_plan_change
PUT /v1/billing/plan
billing:write
Move to a lower plan, or to Free to cancel. Upgrades go through billing_checkout_create.
billing_autorecharge_set
PUT /v1/billing/auto-recharge
billing:write
Top up by amount_usd whenever the balance drops below threshold_usd.
billing_simulate
POST /v1/billing/simulate
billing:write
Test and simulated modes only: payment failure, dispute (freezes the org), refund, renewal, downgrade, cancel, auto-recharge, grant expiry, or reset simulated state.
options_schema
GET /v1/options/schema
public
JSON Schema of ExecutionOptions: timing, concurrency, rate limits, cost, routing, data and cache, delivery, identity and observability. Every request body accepts it as options.
options_resolve
POST /v1/options/resolve
catalog:read
What a request would run with: request options over the preset, your key's defaults and the workspace defaults, clamped by your plan. Returns where each value came from and what was clamped.
options_defaults_get
GET /v1/options/defaults
logs:read
The workspace's default ExecutionOptions (the lowest precedence layer).
options_defaults_put
PUT /v1/options/defaults
presets:write
Replace the workspace's default ExecutionOptions (cache TTLs per field class, log level, timeouts…). Applies to every key within 30 seconds.
keys_options_set
PUT /v1/keys/{id}/options
keys:write
Default ExecutionOptions for one API key, between the preset and the workspace defaults. Send {} to clear.
cache_stats
GET /v1/cache/stats
logs:read
Records (entities and exact responses), bytes, hits and the vendor spend cache hits saved this month and all time, plus daily hit/partial/miss counts. Cache hits are always free.
cache_list
GET /v1/cache
logs:read
The cache explorer: each cached entity or response with its masked label, fields, their ages and freshness, hits and savings. Values are never returned here.
cache_purge
DELETE /v1/cache
cache:write
Delete cached records by key, tag or capability, or everything with all=true (crypto-shreds the workspace cache key: nothing sealed before can be read again).
cache_forget
POST /v1/cache/forget
cache:write
DSAR delete for the private cache: every cached record about this subject (entity records under all its identities and exact responses naming it) is removed.
cache_feedback
POST /v1/cache/feedback
cache:write
Negative feedback, such as a bounce: the named fields are dropped from the subject's cached record so the next request fetches them again.
logs_tail
GET /v1/logs/live/recent
logs:read
The newest events from the live tail (calls, waterfall run steps, jobs, lists and alerts), newest last, with the same filters as the stream: provider, capability, status, key, app, run or waterfall, minimum latency and cost, sample and fields. Stream them with GET /v1/logs/live or the logs://live MCP resource.
logs_live_ticket
POST /v1/logs/live/ticket
logs:read
A single-use ticket valid for 60 seconds that opens GET /v1/logs/live without an Authorization header (browsers). Carries logs:read for this org only.
drains_list
GET /v1/drains
logs:read
Log drains with their target, filter, batching and delivery health. Credentials are never returned.
drains_create
POST /v1/drains
credentials:write
Send the live log to an HTTPS webhook (HMAC-signed), Axiom, Datadog, or S3, GCS or R2 as NDJSON. Credentials are stored encrypted in the vault and are write-only. Webhook drains return their signing secret once.
drains_get
GET /v1/drains/{id}
logs:read
One drain with its delivery health.
drains_update
PUT /v1/drains/{id}
credentials:write
Rename, pause or resume, change the target, filter or batching, or replace credentials.
drains_delete
DELETE /v1/drains/{id}
credentials:write
Stop sending and remove the drain and its stored credentials.
drains_test
POST /v1/drains/{id}/test
credentials:write
Send one sample event to the drain now and report the result; updates drain health.
alerts_summary
GET /v1/alerts/summary
logs:read
Open alerts by severity, when the last one fired, and how many rules, destinations and webhook endpoints the workspace has.
alerts_rules_list
GET /v1/alerts/rules
logs:read
Every alert rule with its metric, threshold, window, scope, severity, destinations, mute and live state (ok, firing, muted, no_data). New workspaces start with defaults (a vendor key failing, budgets at 80% and 100%, billing mismatches, error-rate and spend spikes, a key on a new IP, failing deliveries, security events).
alerts_rules_create
POST /v1/alerts/rules
keys:write
Alert when a metric crosses a threshold over a window: error_rate, p95_latency, spend, budget_used, vendor_failure_spike, vendor_key_failing, billing_mismatch, cache_hit_rate, delivery_backlog, security_event or new_ip. Scope it to the workspace, a key, a vendor or a capability; route it to every destination or to chosen ones.
alerts_rules_get
GET /v1/alerts/rules/{id}
logs:read
One alert rule with its state.
alerts_rules_update
PUT /v1/alerts/rules/{id}
keys:write
Change any field; fields you leave out keep their value. Changing what the rule measures resolves its open alerts.
alerts_rules_delete
DELETE /v1/alerts/rules/{id}
keys:write
Delete the rule and resolve its open alerts.
alerts_rules_mute
POST /v1/alerts/rules/{id}/mute
keys:write
Snooze a rule for minutes (or until until); it keeps evaluating and recording alerts but sends nothing. minutes: 0 unmutes.
alerts_rules_test
POST /v1/alerts/rules/{id}/test
keys:write
Send a test alert to every destination the rule notifies, now, and report each result. Nothing is recorded as a real alert.
alerts_destinations_list
GET /v1/alerts/destinations
logs:read
Where alerts go (email, webhook endpoints, Slack, Discord, Microsoft Teams, PagerDuty, Opsgenie) with delivery health. Secrets are masked.
alerts_destinations_create
POST /v1/alerts/destinations
credentials:write
Connect email recipients (with optional hourly or daily digests), a webhook endpoint, a Slack or Discord incoming webhook, a Microsoft Teams Workflows URL, a PagerDuty Events API v2 integration key or an Opsgenie API key. The secret is stored encrypted in the vault and never returned.
alerts_destinations_get
GET /v1/alerts/destinations/{id}
logs:read
One destination with its delivery health.
alerts_destinations_update
PUT /v1/alerts/destinations/{id}
credentials:write
Rename, pause or resume, change the minimum severity or settings, or replace the secret.
alerts_destinations_delete
DELETE /v1/alerts/destinations/{id}
credentials:write
Stop sending there and delete its stored secret. Rules that listed it stop routing to it.
alerts_destinations_test
POST /v1/alerts/destinations/{id}/test
credentials:write
Deliver a test alert now and report the result (PagerDuty and Opsgenie tests open and immediately resolve their own incident). Test emails are queued.
alerts_list
GET /v1/alerts
logs:read
Alerts newest first: open (triggered or acknowledged) or resolved, with how often each repeated and its timeline of notifications.
alerts_get
GET /v1/alerts/{id}
logs:read
One alert with its full timeline.
alerts_acknowledge
POST /v1/alerts/{id}/acknowledge
keys:write
Mark an open alert as being handled. PagerDuty and Opsgenie destinations are acknowledged too.
alerts_resolve
POST /v1/alerts/{id}/resolve
keys:write
Close an open alert now; destinations that get resolve notifications are told. The rule's cooldown starts from here.
webhooks_event_types
GET /v1/webhooks/event-types
logs:read
Every event a webhook endpoint can subscribe to, with when it is sent and the current api_version.
webhooks_endpoints_list
GET /v1/webhooks/endpoints
logs:read
Webhook endpoints with their subscriptions, status and delivery health. Secrets are never returned.
webhooks_endpoints_create
POST /v1/webhooks/endpoints
credentials:write
Receive events at an HTTPS URL, signed per Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature). Returns the whsec_ signing secret once.
webhooks_endpoints_get
GET /v1/webhooks/endpoints/{id}
logs:read
One endpoint with its delivery health.
webhooks_endpoints_update
PUT /v1/webhooks/endpoints/{id}
credentials:write
Change the URL, description or subscribed events, or enable and disable it (re-enabling an automatically disabled endpoint clears its failure count).
webhooks_endpoints_delete
DELETE /v1/webhooks/endpoints/{id}
credentials:write
Stop delivering, delete its secrets and delivery log.
webhooks_endpoints_rotate_secret
POST /v1/webhooks/endpoints/{id}/rotate-secret
credentials:write
Issue a new signing secret. The old one keeps signing alongside it for overlap_s (default 24 hours), so both verify while you deploy the new one. Returns the new secret once.
webhooks_endpoints_test
POST /v1/webhooks/endpoints/{id}/test
credentials:write
Deliver an example event of the given type (marked test: true) to the endpoint now and return the delivery with its attempt.
webhooks_deliveries_list
GET /v1/webhooks/deliveries
logs:read
Recent deliveries newest first with every attempt's status code, latency and a redacted response snippet. Kept 30 days.
webhooks_deliveries_get
GET /v1/webhooks/deliveries/{id}
logs:read
One delivery with its attempts and the start of the signed body.
webhooks_deliveries_replay
POST /v1/webhooks/deliveries/{id}/replay
credentials:write
Send a delivery again with the same webhook-id (receivers that dedupe on it ignore a duplicate) and a fresh retry schedule.