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

# Mcp Ingest Code Occurrences

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

## Request

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

Post ONE batch of a key-usage run: where each key is referenced in the code.

MCP twin of `POST /v1/projects/{id}/code-occurrences`. Lifecycle: omit
`scan_id` to OPEN a run (the response mints + echoes it), echo it on follow-up
batches, send `final=true` on the last to CLOSE (reconcile `gone` + mass-gone
guard). Each `ref` is resolved server-side to the BASE-version key_uuid; refs
matching no live base key are counted `unresolved` and echoed, never stored.

IMPORTANT: the response ALWAYS carries `scan_id` when supported. Treat its
ABSENCE as a backend that predates this contract and do NOT drop occurrences
silently.

## Path parameters

- `project_id` string, required

## Request body

- McpCodeOccurrencesIngestIn
  - `occurrences` McpCodeOccurrenceIn[]: One BATCH of key-usage sites {ref, file, line, column?}. All occurrences of a given (key, file) MUST be in the same batch (chunk by file).
    - `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
  - `scan_id` string, nullable: Omit on the FIRST batch to open a run (the response mints + echoes the id); echo it on every follow-up batch.
  - `final` boolean: Set true on the LAST batch to close the run: reconcile `gone` + mass-gone guard.
  - `meta` object, nullable: Run context (tool, version, sha).
  - `confirm_mass_gone` boolean: Only set when a final 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)