---
title: "Mcp Apply Code Occurrences Delta"
method: POST
path: "/v1/mcp/projects/{project_id}/code-occurrences/delta"
tags: ["mcp"]
---

# Mcp Apply Code Occurrences Delta

`POST /v1/mcp/projects/{project_id}/code-occurrences/delta`

## Request

- Base URL: `https://api.sonenta.dev`
- URL: `https://api.sonenta.dev/v1/mcp/projects/{project_id}/code-occurrences/delta`
- Auth: none declared

Apply a CLI-computed delta in ONE call: insert `added`, retire `removed`.

The scalable path: the CLI fetches `catalogue`, diffs locally, and sends only
the change, so the server resolves + writes O(delta), not O(project). Opens and
finalizes one run. `base_version` guards against a concurrent scan — a mismatch
is a 409, on which you refetch the catalogue and recompute. A `removed` that
would retire most live occurrences is a 422 unless `confirm_mass_gone`.

## Path parameters

- `project_id` string, required

## Request body

- McpCodeOccurrencesDeltaIn
  - `added` McpCodeOccurrenceIn[]: Sites present in the scan but NOT in the catalogue: {ref, file, line, column?}.
    - `ref` string, required: Raw usage reference, e.g. `common:actions.save`. NO uuid.
    - `file` string, required: Repo-relative path of the usage site.
    - `line` integer
    - `column` integer, nullable
  - `removed` McpCodeOccurrenceIn[]: Sites present in the catalogue but NOT in the scan (identity is the position {ref, file, line, column}). A moved occurrence is a remove + an add.
    - `ref` string, required: Raw usage reference, e.g. `common:actions.save`. NO uuid.
    - `file` string, required: Repo-relative path of the usage site.
    - `line` integer
    - `column` integer, nullable
  - `base_version` string, nullable: The catalogue `version` this delta was computed against. Must equal the project's latest finalized run, else 409 (refetch + recompute). Null on a project never scanned.
  - `meta` object, nullable: Run context (tool, version, sha).
  - `confirm_mass_gone` boolean: Only set when a delta that retires most live occurrences is intended; else 422.

## Response `200`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/sonenta/apis/sonenta-api.md) · [All operations](https://skmtc.dev/sonenta/apis/sonenta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sonenta/apis/sonenta-api/revisions/f853ea49fb05?raw)