> ## Documentation Index > Fetch the complete documentation index at: https://docs.devtune.ai/llms.txt > Use this file to discover all available pages before exploring further. # API migration guide > Breaking changes to the DevTune REST API and MCP server, and what an existing integration needs to change. This page lists the changes that can break an existing REST or MCP integration, and what to change, newest first. The [API overview](https://docs.devtune.ai/api-reference/overview.md) and the endpoint reference describe the current contract. ## Results method v2 `GET /api/v2/projects/{projectId}/outcomes/ledger` and `devtune_get_outcomes_ledger` add `items[].method`, either `v1` or `v2` for closed Results windows with evidence and `null` while open or for Agent Picks rows. Agent Picks keeps `agentPicks.method`. Timeline `outcome_measured` events add `measuredAction.method`. New closes use v2. It requires full coverage for a conclusive metric, matches citation prompts across windows, counts fetch exposure only while the sensor covered the window, and allows for daily-count dependence. Closed v1 windows keep their results. Preserve `method` when exporting or comparing results. See [Results](https://docs.devtune.ai/insights-actions/outcomes.md). ## Visibility ranges and unmeasured values **Changed:** 31 October 2026. Visibility rates now come with a 90% range, and values that were reported as `0` when nothing was measured are now `null`. Treat each of these fields as nullable: | Read | Fields that can now be `null` | | - | - | | `GET /visibility/summary`, `devtune_get_visibility_summary` | `brandAwareness` when no answer was measured; `shareOfVoice` also when no tracked brand was cited | | `GET /competitive/position`, `devtune_get_competitive_position` | `totals.primaryShare`, `totals.primaryShareOfAllCitations`, `totals.shareOfVoice` | | `GET /visibility/diff` | the same `totals` fields in `current` and `previous`, and `delta.primaryShare` | | `GET /citations/stats`, `devtune_get_citation_stats` | `stats.avgPosition` | | `GET /citations/top-pages`, `GET /citations/top-domains` and their MCP tools | `avgPosition` on a row with no positioned citation | | `devtune_get_intelligence_forecast` | `summary.confidence.primaryCitations` and `summary.trend` when the window has no data | These fields are new and additive: * Every rate above gains a sibling `Range` object: `value`, `low` and `high` in the unit of the rate, `successes`, `n`, `nEffective`, `confidence` (`0.9`), `directional` and `method`. `directional` is `true` when the rate rests on fewer than 10 effective samples. The visibility summary has `shareOfVoiceRange`, `citationPresenceRange`, `brandAwarenessRange`, `advertising.primaryRateRange` and `advertising.competitorRateRange`. `citationPresenceRange` counts citation-eligible answers in `n`. * `GET /visibility/diff` gains `delta.shareOfVoice` and `comparisons.primaryShare` and `comparisons.shareOfVoice`. Each comparison has `comparison` (`up`, `down`, `no_clear_change` or `not_comparable`), `notComparableReason`, and the change with its 90% interval in percentage points. Report a change only when `comparison` is `up` or `down`. * The new MCP tool `devtune_get_visibility_diff` returns the same diff as REST and needs `visibility.read`. How to read a range, **Directional** and a clear change is explained in [Ranges, leads and clear changes](https://docs.devtune.ai/search-tracking/visibility-metrics.md#ranges-leads-and-clear-changes). ## Brand deletion confirmation for positioning competitors **Changed:** 29 October 2026. MCP server 5.0.0. On plans with Positioning, `DELETE /projects/{projectId}/setup/brands/{brandId}` can now return `409` where it previously returned `200`. This applies to brands in the project's current positioning competitor set, including the default first five when no usable choice is saved. The response has `error: "conflict"` and `reason: "brand_in_competitor_set"`. Show the customer that deletion changes future comparisons and ends any comparable history for the current set. After they confirm, retry REST with `?confirm=true`, or retry `devtune_delete_brand` over MCP with `confirm: true`. Cancelling requires no retry and deletes nothing. Brands outside the set and accounts on plans without Positioning need no confirmation. Recorded sets stay in history. ## Nullable traffic summary counts **Changed:** 27 October 2026. In `GET /projects/{projectId}/traffic/summary` and `devtune_get_traffic_summary`, the six counts (`totalEvents`, `botEvents`, `referralEvents`, `uniqueSessions`, `botSessions` and `referralSessions`) can now be `null`, both in the window totals and in each `daily` row. A day is `null` when no crawler sensor covered it, and a window total is `null` when no day in the window was covered. Treat these fields as nullable, and use `coverage.coveredDays` against `coverage.windowDays` to see how much of the window a total covers. ## Agent Picks test management and schedules **Changed:** 24 October 2026. MCP server 4.0.0. Your own agents can quote, start and cancel Agent Picks tests and re-tests, start the starter test, enable and turn off schedules, and edit the setup and custom job. Spending credits needs the `agent_picks.run` scope. See [Agent Picks API and MCP](https://docs.devtune.ai/agent-picks/api-and-mcp.md) for the quote token, `max_credits`, cancellation and every refusal reason. * `PATCH /projects/{projectId}/agent-picks/schedule` is removed. Enable or change a cadence with `PUT` on the same path, which takes `cadence`, a `quote_token` from a schedule quote and `max_credits`, and needs `agent_picks.run`. Turn the schedule off with `DELETE`, which needs `actions.write`. * The MCP tool `devtune_set_agent_picks_schedule` is replaced by `devtune_enable_agent_picks_schedule` (`agent_picks.run`) and `devtune_disable_agent_picks_schedule` (`actions.write`). * Existing API keys and OAuth connections do not gain `agent_picks.run`. Add it to a key under API Keys, or reconnect an MCP client and approve it, before enabling schedules or starting tests. * `PATCH /projects/{projectId}/agent-picks/settings` checks the member who created the API key, as schedules do. A key whose creator has left the account or cannot edit the project is refused with `403`. ## Agent Picks model cost fields removed **Changed:** 23 October 2026. Agent Picks is billed in credits, so its reads no longer return model cost in dollars. The MCP tools return the same fields as REST. | Read | Removed fields | | - | - | | Run list, run detail, starter test | `model_spend_usd`, `model_spend_incomplete` | | Paid test runs | `cost_usd`, `spend_unknown` | | Run trace | `totals.cost_usd`, `totals.unpriced_calls`, `unplaced[].cost_usd`, and `cost_usd`, `running_total_usd` and `spend_is_lower_bound` in a `model_call` item's `detail` | Model call counts and token counts remain. Read what a paid test charged from its credit fields: `reserved_micros`, `settled_micros` and `refunded_micros` on the test, and `settled_micros` on each run. ## Knowledge Profile fields **Changed:** 18 September 2026. `PATCH /projects/{projectId}/knowledge` no longer accepts the `positioning` and `products_services` write fields. Write that material to `company_context`. Existing values in those fields remain readable. ## Retired endpoints **Changed:** 14 September 2026. The intelligence anomaly endpoint and its MCP tool are retired. For detected changes and events, use `GET /projects/{projectId}/timeline/events` or the `devtune_get_timeline_events` MCP tool. Both require `visibility.read`. ## Content gaps **Changed:** 4 September 2026. `GET /projects/{projectId}/content-gaps/list` and `devtune_get_content_gaps` return measured topic, source and brand citation counts over a fixed 30- or 90-day window. `estimated` is always `false`. They no longer return `impactScore`, `confidenceScore`, `freshnessScore`, `actionabilityScore`, `signalStrength`, `signals`, `evidence`, `candidateKey`, `summary`, prompt counts or third-party citation counts. These values cannot be reproduced from measured citations, so DevTune does not substitute estimates. Use [Get content gap evidence](https://docs.devtune.ai/api-reference/get-content-gap-evidence.md) for the prompts and pages behind a gap, and Actions for workflow state, briefs and recommended work. ## Deprecated pagination parameters Lists that paged by `offset`, `page`, `generation` or `snapshotId` still accept them, but they are deprecated. Move to `cursor` as described under [Pagination](https://docs.devtune.ai/api-reference/overview.md#pagination). Sending a deprecated parameter beside `cursor` returns `400`. ## MCP connections approved before current scopes An MCP connection keeps the scopes it was approved with. A connection approved before a tool family existed cannot use those tools or run agents until you approve the expanded access: revoke the client's OAuth authorization and connect again. A reconnect that skips the consent screen does not add scopes. See [MCP permissions](https://docs.devtune.ai/api-reference/mcp-server.md#permissions). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.