# SignalMD

> SignalMD diagnoses production voice agents. It tells you what to fix and whether the fix worked.

- [Introduction](https://docs.signalmd.dev/index.md): SignalMD tells the owner of a production voice agent what to fix and whether the fix worked.
- [Quickstart](https://docs.signalmd.dev/quickstart.md): Sign up, connect a Retell agent, import its recent calls, approve the brief and read your first issues.
- [How SignalMD works](https://docs.signalmd.dev/concepts/how-signal-works.md): What you get from SignalMD, from the first calls on your board to knowing whether a fix worked, and what you can rely on in what it says.
- [The brief](https://docs.signalmd.dev/concepts/the-brief.md): The short document that says what your agent is for and what a good call is. SignalMD drafts it, you correct it, and every number is measured against it.
- [Calls and flow](https://docs.signalmd.dev/concepts/traces.md): What you see on a call page and on the Flow page, and why SignalMD keeps each call's full record.
- [Lanes](https://docs.signalmd.dev/concepts/lanes.md): The five places a defect can live: Hearing, Understanding, Flow and state, Speaking and Integrations, and who usually owns each fix.
- [Issues](https://docs.signalmd.dev/concepts/issues.md): What an issue is, which issues reach the Fix and Improve sections, what each issue contains, and how SignalMD tells you whether your fix worked.
- [Signals](https://docs.signalmd.dev/concepts/signals.md): Small observations about moments in a call, shown on the call page. They help explain an issue and are never an issue on their own.
- [Versions](https://docs.signalmd.dev/concepts/versions.md): How SignalMD picks up a new version of your agent, what it compares, and how to read the verdicts it gives.
- [Connect Retell](https://docs.signalmd.dev/guides/connect-retell.md): Connect a Retell agent with an API key, keep its calls flowing in, add more agents, and replace or remove a connection.
- [Fix an issue](https://docs.signalmd.dev/guides/fix-an-issue.md): Go from an issue on the board to a shipped change in your agent, and confirm the change worked.
- [Compare versions](https://docs.signalmd.dev/guides/compare-versions.md): Check whether a change helped: where the comparison lives, how to read each verdict, what to do next, and how to get it over the API.
- [Test a fix](https://docs.signalmd.dev/guides/test-a-fix.md): Turn production calls into tests, run them against a version of your agent, and read what a pass and a fail mean.
- [Auto-improve tests](https://docs.signalmd.dev/guides/auto-improve-tests.md): When a run of a test finishes, SignalMD checks whether the result was right and fixes the test when the test, not your agent, was at fault.
- [AI copilot overview](https://docs.signalmd.dev/copilot/overview.md): An AI assistant that reads your issues and calls, drafts fixes to your prompt or flow, and tests them. Publishing to Retell always takes an admin's click.
- [Build](https://docs.signalmd.dev/copilot/build.md): Draft a fix, test it against your calls, compare the results and publish it to Retell from one page, with a way back.
- [Pricing](https://docs.signalmd.dev/billing/pricing.md): SignalMD's plans, what a credit buys, and what happens when your credits run out.
- [Billing FAQ](https://docs.signalmd.dev/billing/faq.md): Answers about usage, upgrading, downgrading, cancelling, invoices and payments.
- [Limits and quotas](https://docs.signalmd.dev/limits.md): Plan credits, API rate limits, the plan limit error, import size, copilot limits and when a version comparison can give a verdict.
- [Data and security](https://docs.signalmd.dev/data-and-security.md): What SignalMD stores from your Retell calls, who processes it, how it is secured, and how it is retained and deleted.
- [Glossary](https://docs.signalmd.dev/glossary.md): Short definitions of the terms you meet in the SignalMD app and docs, each linking to the page that explains it.
- [API introduction](https://docs.signalmd.dev/api/introduction.md): Use the SignalMD API to read issues, calls and versions from your own tools, and to wire SignalMD into CI.
- [Authentication](https://docs.signalmd.dev/api/authentication.md): Make an API key in the app, send it as a bearer token, and choose between read and write access.
- [MCP overview](https://docs.signalmd.dev/mcp/overview.md): Give Claude, Cursor or another AI assistant access to your SignalMD issues, calls, versions and tests, with read access by default.
- [Connect your client](https://docs.signalmd.dev/mcp/clients.md): Copy-paste setup for Claude Code, Claude Desktop, Cursor, VS Code and any other MCP client.
- [List agents](https://docs.signalmd.dev/api-reference/agents/list-agents.md): The workspace's agents, newest first, and the shared demo agent when it is on (marked `readOnly`). A key tied to one agent sees only that agent.
- [Get an agent](https://docs.signalmd.dev/api-reference/agents/get-an-agent.md): One agent with counts of its calls, open issues, versions and tests.
- [Get an attempt](https://docs.signalmd.dev/api-reference/runs/get-an-attempt.md): One simulated call: its transcript, the verdict on each criterion with who decided it, what SignalMD's own checks found, caller drift, and what played and scored it.
- [List runs](https://docs.signalmd.dev/api-reference/runs/list-runs.md): Test runs of this agent, newest first, each with its progress, cost and summary.
- [Start a run](https://docs.signalmd.dev/api-reference/runs/start-a-run.md): Plays tests (a set, or a list) against one agent version as simulated calls, optionally once per persona. This spends: the customer's Retell budget, and for a key, its monthly budget too. A run neither covers is refused with 402 `budget_error` before anything is spent; one they cover in part starts…
- [Get a run](https://docs.signalmd.dev/api-reference/runs/get-a-run.md): One run: status, progress, cost, a summary with calibrated cells counted apart, and the change from the previous comparable run.
- [List a run's attempts](https://docs.signalmd.dev/api-reference/runs/list-a-runs-attempts.md): The simulated calls of one run, newest first, without transcripts. GET .../attempts/{attemptId} has one in full.
- [Rescore a run](https://docs.signalmd.dev/api-reference/runs/rescore-a-run.md): Scores every stored attempt of a finished run again from its transcript with SignalMD's current scoring. No new calls are placed. A key may rescore only what the current scoring epoch would score differently, one rescore at a time, inside its monthly budget (402 when it does not cover it, 409 otherw…
- [Get a run's result document](https://docs.signalmd.dev/api-reference/runs/get-a-runs-result-document.md): The run as one document (schemaVersion 1), the same the CLI writes and webhooks post: every cell with its attempts, verdicts and who decided them, and the change from the previous comparable run, or from `compareTo`.
- [Calibrate tests](https://docs.signalmd.dev/api-reference/runs/calibrate-tests.md): Plays each test several times with its own caller to decide whether it may gate a release: an issue test on the version its source call ran on must reproduce the problem, any other on the version in production must pass every time. Until then a test is shown and never gates. Starts one calibration r…
- [List the tool audit log](https://docs.signalmd.dev/api-reference/insights/list-the-tool-audit-log.md): Every write made on this agent through MCP, the in-app copilot or an API key, and every publish or rollback, refused or not, newest first: who, through which tool, on which ids, a hash of the arguments, and the answer's status.
- [Get the brief](https://docs.signalmd.dev/api-reference/insights/get-the-brief.md): The agent's brief: what it is for, use cases, guardrails and open questions, and when it was generated. The setup conversation is not included.
- [List analysis builds](https://docs.signalmd.dev/api-reference/insights/list-analysis-builds.md): The analysis builds behind the board, signals and callers: which built, when, and whether one stopped.
- [List callers](https://docs.signalmd.dev/api-reference/insights/list-callers.md): Who calls and why: use cases, sub use cases, personas and caller traits, each with call counts and how the agent handled them.
- [Get the live configuration](https://docs.signalmd.dev/api-reference/insights/get-the-live-configuration.md): The live version's editable text (prompts, step instructions, transition conditions), each with the path a draft change uses, plus the version and its hash. Anything that looks like a credential is masked; tool URLs and headers are never included. Long configurations come back in part: pass paths fo…
- [Get the config review](https://docs.signalmd.dev/api-reference/insights/get-the-config-review.md): Findings read from the live configuration (prompt, steps, tools) that are likely to cause trouble. Risks, not measured defects.
- [Get the flow](https://docs.signalmd.dev/api-reference/insights/get-the-flow.md): How calls move through the agent's parts and steps on one version: calls per step, drops and loops, the transitions taken, and how calls end.
- [Get health metrics](https://docs.signalmd.dev/api-reference/insights/get-health-metrics.md): Health metrics over a range, each with the previous period and the board's verdict on the change (changed, within_noise, too_few). Leave metrics out for the default board. groupBy splits each by version, outcome or use_case.
- [List a metric's calls](https://docs.signalmd.dev/api-reference/insights/list-a-metrics-calls.md): The calls that count toward one metric in a range, as the metric's drill-down shows them, grouped as the board groups them (up to 200 per group).
- [Get the overview](https://docs.signalmd.dev/api-reference/insights/get-the-overview.md): The agent's home page as one document: calls in the window, the outcome mix, resolution, containment and abandon rates with the change since the previous version, the current version and the top open issues.
- [Get spend](https://docs.signalmd.dev/api-reference/insights/get-spend.md): What the copilot, quick checks, clients and simulated runs spent on this agent in a period, and by goal. Reported, never capped per goal.
- [Get stats](https://docs.signalmd.dev/api-reference/insights/get-stats.md): Calls by day, version and outcome; listed issues by lane and board section; tests by state, stability and latest verdict; this month's runs and spend. Calls on the test line are left out.
- [List test generations](https://docs.signalmd.dev/api-reference/insights/list-test-generations.md): Each time SignalMD wrote candidate tests (from calls, the configuration, a description or an issue), with its status.
- [Get a test generation](https://docs.signalmd.dev/api-reference/insights/get-a-test-generation.md): One generation in full, with the tests it proposed.
- [Get test settings](https://docs.signalmd.dev/api-reference/insights/get-test-settings.md): Whether testing is set up: enabled, whether a Retell write key is stored (never the key), the monthly budget, what this month spent and what is left, whether runs start automatically, whether auto-improve is on (autoImprove). When a run finds the test at fault, auto-improve checks its fix in text co…
- [List calls](https://docs.signalmd.dev/api-reference/calls/list-calls.md): The agent's production calls, newest first. Calls with no start time come last. Filters combine.
- [Get a call](https://docs.signalmd.dev/api-reference/calls/get-a-call.md): One call with its analysis, who called and why, and the open issues it is evidence for. The transcript is in the call's trace.
- [Get a call's signals](https://docs.signalmd.dev/api-reference/calls/get-a-calls-signals.md): What was noticed on one call: the signals raised and the observations made. A signal is a symptom noticed on a call, not a diagnosed issue: the issues say where a problem is, why, and what to change.
- [Get a call's trace](https://docs.signalmd.dev/api-reference/calls/get-a-calls-trace.md): The call as SignalMD reads it: turns, tool calls, the path through the flow, latency by layer, and measurements. Facts the platform recorded, with none of its own judgements.
- [Get a call's test match](https://docs.signalmd.dev/api-reference/tests/get-a-calls-test-match.md): Which accepted test the call is an instance of, how sure SignalMD was, and how the call was checked against the test's criteria. 404 `case_match_not_found` when the call was never matched: the agent has no accepted tests, the call is not labelled yet, nobody spoke, or it came from the agent's own te…
- [List call matches](https://docs.signalmd.dev/api-reference/tests/list-call-matches.md): Every call matched or checked against the agent's accepted tests, newest decision first.
- [Get test coverage](https://docs.signalmd.dev/api-reference/tests/get-test-coverage.md): SignalMD's test plan and gaps: which calls it would test and why, coverage cells it could not fill, brief lines that get a probe, and tests it would retire. Reads only.
- [List criteria proposals](https://docs.signalmd.dev/api-reference/tests/list-criteria-proposals.md): The agent's criteria proposals, newest first, at most 200. Pending ones unless `status` says otherwise.
- [List improvement batches](https://docs.signalmd.dev/api-reference/tests/list-improvement-batches.md): When one run of several tests finds the same kind of gap in more than one of them, those tests improve together, and a gap they share is fixed once for all. Newest first, up to `limit` (one page).
- [Get an improvement batch](https://docs.signalmd.dev/api-reference/tests/get-an-improvement-batch.md): Where one improvement batch stands, its totals, and each test in it.
- [List personas](https://docs.signalmd.dev/api-reference/tests/list-personas.md): The callers a test can be played by, all of them in one response: each test's own (@source), personas read from the agent's calls, the standard callers, and custom personas. Real callers' sample lines are left out.
- [List test groups](https://docs.signalmd.dev/api-reference/tests/list-test-groups.md): Every test set, then a group per use case and per persona the tests carry, each with passing, failing, flaky, draft and unrun counts. Archived tests are left out.
- [List test sets](https://docs.signalmd.dev/api-reference/tests/list-test-sets.md): The agent's test sets by name. The release set (`isRelease`) is what runs on every new version and from CI.
- [Get a test set](https://docs.signalmd.dev/api-reference/tests/get-a-test-set.md): One test set with its member test ids.
- [List tests](https://docs.signalmd.dev/api-reference/tests/list-tests.md): The agent's tests, newest first, each with its gate state and latest result. Archived tests are left out unless asked for.
- [Create a test](https://docs.signalmd.dev/api-reference/tests/create-a-test.md): Makes a test from a spec (custom or probe), or from a stored production call (`callId`, and `issueKey` to test that issue). Free: nothing runs. A refused spec is a 400 `invalid_spec`; POST .../tests/validate lists every problem.
- [Get a test](https://docs.signalmd.dev/api-reference/tests/get-a-test.md): One test with its spec, the shape create and edit take, and its criteria resolved against the current brief. Personal values stay masked.
- [Replace a test's spec](https://docs.signalmd.dev/api-reference/tests/replace-a-tests-spec.md): Replaces what the spec covers and makes a new revision. An edit that changes what is played or checked clears the calibration, so the test stops gating until calibrated again. An archived test is refused (422). Once a person approved the test's criteria, a change to any criterion (rewording included…
- [Propose a criteria change](https://docs.signalmd.dev/api-reference/tests/propose-a-criteria-change.md): Files a change to the test's criteria for a person to approve or reject in SignalMD, and changes nothing now. Send the test as it should be; a spec that leaves the criteria as they are is 422 `no_criteria_change` (edit the rest with PATCH). A newer proposal supersedes a pending one for the same test…
- [Get a test's production pass rate](https://docs.signalmd.dev/api-reference/tests/get-a-tests-production-pass-rate.md): The test's pass rate on production calls matched to it, at its current revision, and the matched calls. Failing calls by default; `result=all` lists every one. A failed criterion says what went wrong on the call, not why.
- [List a test's revisions](https://docs.signalmd.dev/api-reference/tests/list-a-tests-revisions.md): Every revision of a test, newest first, each as a spec. An attempt names the revision it ran (`testRevision`).
- [Get a test's stability](https://docs.signalmd.dev/api-reference/tests/get-a-tests-stability.md): Whether the recent runs of the current revision agree, read from the recorded runs. What a verdict may say follows from this.
- [List a test's verdicts](https://docs.signalmd.dev/api-reference/tests/list-a-tests-verdicts.md): Every verdict recorded on the test, newest first, each with the revision it is about.
- [Record a verdict](https://docs.signalmd.dev/api-reference/tests/record-a-verdict.md): Records a verdict on the test's current revision. The runs are read here, not taken from the request. A verdict the runs do not support is refused with 422 `verdict_not_supported`: stable needs the runs to pass, bot_defect needs them to fail the same way, and bot_flaky needs mixed results; both of t…
- [Accept draft tests](https://docs.signalmd.dev/api-reference/tests/accept-draft-tests.md): Accepts drafts, so they gate and count from now on. Each needs criteria a person approved, a verdict on its current revision that its runs still support, and no test_issue on that revision. 200 whatever was refused; `refused` says why. An id that is not this agent's test refuses the whole request wi…
- [Get the test spec schema](https://docs.signalmd.dev/api-reference/tests/get-the-test-spec-schema.md): The TestSpec JSON Schema, and what this agent's specs can name: brief references, tools that take a fixture, personas and sets.
- [Validate a test spec](https://docs.signalmd.dev/api-reference/tests/validate-a-test-spec.md): Checks a spec as create (or, with `testId`, as an edit of that test) would, and stores and spends nothing. 200 whatever the result: `ok` says whether it would be stored. A read key may call it.
- [List version comparisons](https://docs.signalmd.dev/api-reference/comparisons/list-version-comparisons.md): Stored comparisons, newest version first: one per pair of consecutive versions SignalMD recorded.
- [Get a version comparison](https://docs.signalmd.dev/api-reference/comparisons/get-a-version-comparison.md): One stored comparison.
- [List drafts](https://docs.signalmd.dev/api-reference/drafts/list-drafts.md): The agent's drafts, most recently changed first (up to 100).
- [Create a draft](https://docs.signalmd.dev/api-reference/drafts/create-a-draft.md): Saves a change to the live version's prompt or flow text as a draft. Nothing reaches Retell. A draft for an issue whose cause is not established is refused with 409 `cause_not_established`.
- [Get a draft](https://docs.signalmd.dev/api-reference/drafts/get-a-draft.md): One draft: its diff against its base, its quick checks and runs, the evidence for this exact text, and whether it can be published.
- [Update a draft](https://docs.signalmd.dev/api-reference/drafts/update-a-draft.md): Changes a draft that is not published: title, rationale, more changes over its current text, or its new cases. A change to the text bumps the revision and voids every test of the earlier text.
- [Publish a draft](https://docs.signalmd.dev/api-reference/drafts/publish-a-draft.md): Publishes the draft to the live agent: what callers hear next. A key must be a write key made with can_publish (403 `key_cannot_publish` otherwise), and the whole accepted suite must have run and passed on this exact text (403 `no_suite_run`, `suite_running`, `suite_failed` or `suite_incomplete`). c…
- [Quick-check a draft](https://docs.signalmd.dev/api-reference/drafts/quick-check-a-draft.md): SignalMD simulates callers against the draft's text with its own model and scores them. Approximate, never proof. Costs model tokens, metered per workspace.
- [Test a draft](https://docs.signalmd.dev/api-reference/drafts/test-a-draft.md): Runs the draft in Retell's simulation on a shadow copy at its exact text. attempt: the draft's new cases plus the guard set, refused with 422 `not_reproduced` until every new case reproduces the problem on the live agent. full_suite: every accepted case, the run a publish through the API needs. This…
- [List goals](https://docs.signalmd.dev/api-reference/goals/list-goals.md): The agent's goals, newest first.
- [Start a goal](https://docs.signalmd.dev/api-reference/goals/start-a-goal.md): Opens a goal: a record that groups the cases, verdicts, runs and drafts made for one request, and what they cost. Nothing runs.
- [Get a goal's status](https://docs.signalmd.dev/api-reference/goals/get-a-goals-status.md): The goal as it stands, computed from the store: each case's state, stability and latest verdict, the criteria proposals still pending, its drafts and runs, and its spend.
- [Approve a goal's plan](https://docs.signalmd.dev/api-reference/goals/approve-a-goals-plan.md): A person approves the goal's plan: the cases it will work with and their criteria. Until then the in-app copilot starts no Retell run for it. People only: every API key is refused with 403 `people_only`, and so is the copilot.
- [Close a goal](https://docs.signalmd.dev/api-reference/goals/close-a-goal.md): Closes the goal. Its record and spend stay; the copilot runs nothing more for it.
- [Report spend](https://docs.signalmd.dev/api-reference/goals/report-spend.md): Records model spend a client paid for while working on the goal. Reported, not checked, and never capped.
- [List issues](https://docs.signalmd.dev/api-reference/issues/list-issues.md): The agent's issues as its board shows them, Fix, Improve and Cause not established together, highest priority first, with any issue the live version fixed (`fellOnLive`: none of its calls shows it) after every one still happening: open ones, without consequences of another issue unless asked for. On…
- [Get an issue](https://docs.signalmd.dev/api-reference/issues/get-an-issue.md): One issue: where, why, what to change, how sure, how many evidence calls, how its calls split by version, the agent's grace period (`graceDays`) and whether the live version fixed it (`fix`), read with that grace period.
- [List an issue's evidence calls](https://docs.signalmd.dev/api-reference/issues/list-an-issues-evidence-calls.md): The calls linked to the issue as evidence, newest first, each with the samples the issue keeps from it.
- [List signals](https://docs.signalmd.dev/api-reference/signals/list-signals.md): For each signal code, how many of the agent's analysed calls in the window carry it, most calls first. A signal is a symptom noticed on a call, not a diagnosed issue: a common signal can have several causes or none worth fixing, and the issues say where a problem is, why, and what to change.
- [List versions](https://docs.signalmd.dev/api-reference/versions/list-versions.md): The agent's versions, newest first: every version whose configuration was captured and every version an analysed call ran on, with its calls and outcome rates.
- [Get a version](https://docs.signalmd.dev/api-reference/versions/get-a-version.md): One version with its calls, Got it done, Handed to a person and captured configuration.
- [Compare two versions](https://docs.signalmd.dev/api-reference/versions/compare-two-versions.md): What changed in the configuration between any two versions, not only neighbours, and what production did across them by the health board's metrics and verdicts (`result`), with the stored comparison when one exists for that pair.
- [List watches](https://docs.signalmd.dev/api-reference/watches/list-watches.md): The agent's watches, newest first. Issue-origin watches (ones that only measure an issue) are left out.
- [Create a watch](https://docs.signalmd.dev/api-reference/watches/create-a-watch.md): Creates a draft watch and starts a backtest on past calls. A key or the copilot may create drafts; only a person can turn a watch on, once enough sample calls are labelled.
- [Get a watch](https://docs.signalmd.dev/api-reference/watches/get-a-watch.md): One watch with its latest backtest summary and the flagged and cleared sample calls, each with a quote, turn and any right/wrong label.
- [Edit a watch](https://docs.signalmd.dev/api-reference/watches/edit-a-watch.md): Starts a new revision with no labels and runs a new backtest. A live watch must be paused first.
- [Label a sample call](https://docs.signalmd.dev/api-reference/watches/label-a-sample-call.md): Marks a flagged sample call on the current revision right or wrong. Cleared calls are refused (400). Only labels on flagged calls count toward turning the watch on.
- [Set a watch's state](https://docs.signalmd.dev/api-reference/watches/set-a-watchs-state.md): Moves the watch between draft, backtesting, review, live, paused and rejected. Moving to backtesting starts a backtest, which moves the watch to review when it finishes: this is how a suggested draft is kept; rejected dismisses it. Going live needs enough sample calls on the current revision labelle…
- [Who am I](https://docs.signalmd.dev/api-reference/account/who-am-i.md): The principal this token resolves to: workspace, key scope and agent, and the rate limits that apply.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.