Context Intelligence

apply_grounding_fix

Apply Marcora's stored recommended fix for one or more findings, by finding_id. Serves both content-grounding findings and Context Intelligence health-audit recommendations. Review each suggested_fix with the user first - this writes to their library.

Parameters

Name	Type	Required	Default	Description
`finding_ids`	`array`	Yes	—	Required. The finding_id values to apply, from check_content_grounding, get_grounding_result or list_ci_findings. Pass one or many.
`context_item_overrides`	`object`	No	—	Optional. Redirect specific fixes: a map of finding_id to the context_item_id it should be written to instead of the finding's default target. Every key must also appear in finding_ids. Mirrors the destination picker in the Marcora UI.

Input Schema

{
  "type": "object",
  "required": [
    "finding_ids"
  ],
  "properties": {
    "finding_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Required. The finding_id values to apply, from check_content_grounding, get_grounding_result or list_ci_findings. Pass one or many."
    },
    "context_item_overrides": {
      "type": "object",
      "description": "Optional. Redirect specific fixes: a map of finding_id to the context_item_id it should be written to instead of the finding's default target. Every key must also appear in finding_ids. Mirrors the destination picker in the Marcora UI.",
      "additionalProperties": {
        "type": "string",
        "format": "uuid"
      }
    }
  }
}

Output Schema

{
  "type": "object",
  "required": [
    "requested",
    "queued",
    "skipped",
    "jobs",
    "errors"
  ],
  "properties": {
    "jobs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "finding_id": {
            "type": "string",
            "format": "uuid"
          },
          "document_uuid": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "generation_id": {
            "type": "string",
            "format": "uuid",
            "description": "The poll key for get_generation_status. Jobs applied together in one run (fixes landing in the same document) share it."
          },
          "context_item_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Where the fix was written. null means the document itself."
          }
        }
      },
      "description": "One entry per finding that started. Jobs whose fixes land in the same document share a generation_id (one run applies them together); poll each distinct generation_id with get_generation_status."
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "finding_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "description": "One per finding that could not start. Partial success is normal."
    },
    "queued": {
      "type": "integer",
      "description": "How many runs actually started."
    },
    "skipped": {
      "type": "integer",
      "description": "How many could not start - see errors[]."
    },
    "requested": {
      "type": "integer",
      "description": "How many findings were submitted."
    }
  }
}

Instructions

When to use: the user has reviewed findings - from check_content_grounding, get_grounding_result, or list_ci_findings - and wants them acted on.

Review the finding's suggested_fix with the user and get a decision before you call this. It writes to their library.

Applies Marcora's stored recommendation for one or more findings - "yes, do recommendation <id>". You never compose the fix yourself: every finding already carries its recommended update, so applying is purely a reference by finding_id. This is the same action as the Apply button in the Marcora app - same permissions, same billing, same result.

Serves both finding families

Content-grounding findings - the conflicts and gaps from a grounding scan.
Context Intelligence health-audit recommendations - which previously had no apply path at all, so this is new capability for those findings.

Where each fix lands

By default, the context item named in that finding's context_item_id. A null context_item_id means the fix targets the document itself.

Pass context_item_overrides - a map of finding_id to context_item_id - to send a specific fix somewhere else instead.

Asynchronous - and the completion semantics matter

It returns immediately with one job per finding. To follow one to completion, poll get_generation_status with that job's generation_id - a UUID (the response hands you the exact poll key get_generation_status expects).

Findings that land in the same document share one run. Findings whose fixes land in the same document (the same context item, or the same content document when context_item_id is null) are applied together in one run, so their jobs share a generation_id. Poll that generation_id once; its document_updated covers all of them. Brand Foundation findings are not grouped: each keeps its own run and generation_id.

The honest outcome is the document_updated field on that status:

true - the document was actually changed.
false - the recommendation was already covered, and nothing was written.

Report that distinction to the user rather than assuming every applied fix changed something.

Partial success is normal

Findings that could not be started come back in errors[] with a reason, while the rest still run. Check both jobs[] and errors[] - a response is not a failure just because errors[] is non-empty, and it is not a full success just because jobs[] is.

Parameters

Parameter	Type	Required	Description
`finding_ids`	array of uuid	Yes	The findings to apply. One or many
`context_item_overrides`	object	No	Map of `finding_id` to `context_item_id` to redirect specific fixes. Every key must also appear in `finding_ids`

Output

Field	Type	Description
`requested`	integer	How many findings were submitted
`queued`	integer	How many runs actually started
`skipped`	integer	How many could not start - see `errors[]`
`jobs`	array	Per finding: `finding_id`, `status`, `generation_id` (uuid), `document_uuid`, `context_item_id`; jobs whose fixes land in the same document share one `generation_id`, so poll each distinct `generation_id` once
`errors`	array	Per finding: `finding_id`, `error`

Errors

Missing param: finding_ids (400) - pass finding_id values from a prior findings response.
finding_ids must be finding_id UUIDs (400).
context_item_overrides names a finding not in finding_ids (400) - the override would be ignored, so it is rejected rather than silently dropped.
You are not authorized to perform this action (403) - applying requires an admin or editor role.
Per-finding failures, such as a finding that is already resolved or is not a grounding finding, arrive in errors[] rather than as a thrown error.
Marcora is already updating this document. - per finding, in errors[]: another run on that document (for example the user's own Content Assistant request, or an earlier apply_grounding_fix call) is still in progress. Wait for it to finish, then retry those findings.

Example prompts

"Fix the pricing conflict it found"
"Apply all three of those recommendations"
"Add that gap to our positioning doc instead"