Create API Test
create_api_testDefine an API test — a scheduled test of a production HTTP endpoint or MCP server: request + assertions (status/latency/headers/body or MCP tier) executed on an interval, tracking uptime and correctness. Use this to start watching an HTTP endpoint or an MCP server. Set type="HTTP" and the httpTarget/statusPattern params for a web endpoint, or type="MCP" and the mcpTarget params for an MCP server. The URL, headers, body and MCP tool arguments accept Postman-style variables that are resolved once per run: {{uuid}}, {{now}} (ISO 8601 UTC), {{date}}, {{timestamp}} (Unix seconds), {{timestampMs}}, {{timestampNs}}, {{randomInt}} (0-1000) and {{traceId}} (the run's W3C trace id, also sent as the traceparent header). Unknown names are left as written; write {{ for a literal {{. Returns the created API test, including its generated id and current state. Destinations (channelIds) are optional and ADMIN-only; see that parameter. Before it is saved, the test is run once exactly as the schedule will run it (one attempt, no retries). If that trial run passes, the test is created and the response includes the run as trialRun. If it fails, nothing is saved and this call returns an error that says what failed; fix the configuration and call again rather than retrying unchanged. The target URL must be reachable from the public internet; private, loopback and cloud-internal addresses are refused. Run detect_mcp_protocol on the server URL first to see which protocol revisions it speaks.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable name for the API test, e.g. 'checkout API health' | |
| type | Yes | API test type: 'HTTP' for a web endpoint, 'MCP' for an MCP server | |
| mcpUrl | No | MCP only: the MCP server URL to probe | |
| enabled | Yes | Whether the API test starts enabled (scheduled) or paused | |
| httpUrl | No | HTTP only: the http(s) URL to probe. Supports {{uuid}}, {{now}}, {{date}}, {{timestamp}}, {{timestampMs}}, {{timestampNs}}, {{randomInt}} and {{traceId}} variables, resolved once per run; write \{{ for a literal {{. | |
| mcpTier | No | MCP only: assertion depth — HANDSHAKE (just connect), TOOLS_LIST (check expectedTools are advertised) or TOOL_CALL (invoke a tool) | |
| retries | Yes | Retries per run before recording a failure (0-5) | |
| httpBody | No | HTTP only: request body to send; takes the same variables as the URL | |
| toolName | No | MCP TOOL_CALL tier: name of the tool to invoke | |
| channelIds | No | Notification destinations for this test: registry channel UUIDs (the id field from the investigation service's list_alert_channels, not Slack channel ids). Omit to inherit the tenant's API test default (Settings > Notifications); pass an empty list to switch this test's alerts off. Requires the ADMIN role. Not stored here: notification routing is resolved per test, then per source, then the tenant default. Read current destinations with get_api_test_destinations. Change later with set_api_test_destinations. | |
| httpMethod | No | HTTP only: request method — GET, POST, PUT, PATCH, DELETE or HEAD | |
| httpHeaders | No | HTTP only: request headers to send, as a name->value map; values take the same variables as the URL | |
| expectedTools | No | MCP TOOLS_LIST tier: tool names the server must advertise | |
| statusPattern | No | HTTP only: expected status matcher — 3 chars, digits or 'x' wildcards. '200' matches exactly 200; '2xx' matches any 2xx; '20x' matches 200-209 | |
| headerMatchers | No | HTTP only: response headers that must match, as a name->value map | |
| timeoutSeconds | Yes | Per-run timeout in seconds, 1-30 | |
| intervalSeconds | Yes | How often to run the API test, in seconds (minimum 30) | |
| mcpCredentialId | No | MCP only: id of a stored credential to authenticate the MCP session | |
| failureThreshold | Yes | Consecutive failing runs before the API test flips to DOWN (1-10) | |
| httpCredentialId | No | HTTP only: id of a stored credential to authenticate the request (from list_api_test_credentials); omit for an unauthenticated call | |
| maxLatencyMillis | No | HTTP only: fail if response takes longer than this many milliseconds | |
| toolArgumentsJson | No | MCP TOOL_CALL tier: JSON object of arguments to pass to the tool. Supports {{uuid}}, {{now}}, {{date}}, {{timestamp}}, {{timestampMs}}, {{timestampNs}}, {{randomInt}} and {{traceId}} variables, resolved once per run; write \{{ for a literal {{. | |
| bodyValidationTier | No | HTTP only: body validation tier — NONE, VALID_JSON, JSON_CONTAINS (sample fields must be present with the same types, extra fields allowed), JSON_SHAPE (exact field set) or EXACT_MATCH | |
| mcpMaxLatencyMillis | No | MCP only: fail if the API test takes longer than this many milliseconds | |
| mcpProtocolRevision | No | MCP only: protocol revision policy — ANY (the default when omitted), NEWEST_SUPPORTED, or a dated revision: 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25, 2026-07-28. ANY checks that the endpoint answers as an MCP server and records whatever revision it speaks, without asserting it; at the HANDSHAKE tier, a server that answers 401 or 403 when the test has no credential counts as up. NEWEST_SUPPORTED runs against the newest protocol revision the server speaks and moves with it when the server changes. A dated revision pins the test to it and the test fails if the server stops accepting it. Get the server's revisions from detect_mcp_protocol. | |
| bodyValidationSample | No | HTTP only: sample body for JSON_CONTAINS/JSON_SHAPE (a shape template) or EXACT_MATCH tiers | |
| mcpResultValidationTier | No | MCP TOOL_CALL tier: result body validation tier — NONE, VALID_JSON, JSON_CONTAINS (sample fields must be present with the same types, extra fields allowed), JSON_SHAPE (exact field set) or EXACT_MATCH | |
| mcpResultValidationSample | No | MCP TOOL_CALL tier: sample result for JSON_CONTAINS/JSON_SHAPE/EXACT_MATCH validation |