---
title: "Verify and apply or suggest a pipeline change"
method: POST
path: "/v1/pipelines/{jobId}/apply-change"
tags: ["Pipeline Changes"]
---

# Verify and apply or suggest a pipeline change

`POST /v1/pipelines/{jobId}/apply-change`

## Request

- Base URL: `https://docs.grepr.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.grepr.ai/v1/pipelines/{jobId}/apply-change`
- Auth: one of:
  - API key in header `GREPR-API-KEY`
  - OpenID Connect (`https://grepr-prod.us.auth0.com/.well-known/openid-configuration`)

Deep-merges a partial templateInputs patch into the pipeline's current configuration and verifies the result against the supplied samples. A change that fails verification is rejected with findings and nothing is touched. A change that verifies cleanly is recorded as an agent suggestion for human review when the proposing agent requires approval, and applied as a new job version otherwise. Works only on pipelines with a single template-operation vertex.

## Path parameters

- `jobId` string, required

## Request body

- PipelineChangeRequest
  - `autoApply` boolean: Whether to apply the change directly (true) or record it as a suggestion for a human to review (false). This expresses intent only: the server enforces the proposing agent's approval mode, so a suggest-only agent's change is always recorded as a suggestion no matter what is passed here.
  - `changeDescription` string: One or two sentences a human reviewer reads first: what the change does and why. Required when the change is recorded as a suggestion.
  - `changeId` string: A caller-chosen idempotency key for this change, unique within the investigation. Resending the same changeId records one suggestion rather than a duplicate, so a retried call is safe. Required when the change is recorded as a suggestion.
  - `investigationId` string: The investigation proposing the change, identifying the agent whose approval mode governs the request. Server-supplied on the MCP transport, where an agent sandbox's provenance is bound to the connection: anything sent here is ignored and replaced. Without provenance the change is applied under the caller's own permission.
  - `samples` LogEvent[]: Sample log events the changed operations are verified against before anything is applied. Required when the change adds or edits a Grok rule, so the new rule can be run against a real log.
    - `attributes` object: Attributes associated with the event, a map from attribute name to attribute value, which may be a nested map or list.
    - `eventTimestamp` integer, required: Event timestamp that is in the record. Milliseconds from epoch.
    - `id` string, required: Id of the event.
    - `message` string: The log message.
    - `receivedTimestamp` integer, required: Timestamp when the event was received by Grepr. Milliseconds from epoch.
    - `severity` integer: The log severity. Higher numbers mean higher severity, following the OTel format 1-24.
    - `tags` object: Tags associated with the event, a map from tag name to set of tag values.
  - `templateInputsPatch` JsonNode, required: A partial templateInputs object to deep-merge into the pipeline's current inputs. Objects merge recursively, and an array of named objects (like input.parsers) merges by entry name, so entries you omit are kept. Scalars and arrays of non-objects replace whole.

## Response `200`

Change applied, recorded as a suggestion, or rejected with findings

- PipelineChangeResult
  - `appliedVersion` integer: The new job version the change was applied as. Applying restarts the pipeline from a savepoint, so the new version reaches its desired state asynchronously.
  - `findings` ChangeFinding[]: Verification findings that blocked the change. When present the pipeline is untouched: fix the findings and submit again.
    - `code` 'INVALID_GROK_RULE' | 'SAMPLE_PREDICATE_MISMATCH' | 'RULE_NOT_MATCHED' | 'RULE_SHADOWED' | 'RULE_EXTRACTED_NOTHING' | 'RULE_NOT_FOUND' | 'AMBIGUOUS_PREDICATE' | 'NO_SAMPLES' | 'OPERATION_DELETED' | 'RULE_DELETED' | 'HELPER_RULE_DELETED' | 'RESOLUTION_FAILED' | 'DISALLOWED_INPUT_CHANGE' | 'UNVERIFIABLE_CHANGE' | 'NO_EFFECTIVE_CHANGE'
    - `details` object
    - `message` string
    - `sampleId` string
  - `suggestionId` string: The agent suggestion the change was recorded as. The pipeline is NOT updated and will not restart, so there is nothing to wait for and the change must not be resubmitted; a human reviews and applies it from the pipeline page.

## Other responses

- `400`: The request is malformed or the pipeline is not templated
- `401`: Unauthorized
- `404`: Pipeline not found
- `409`: The pipeline changed while the request was being verified

---

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