---
title: "Apply a pending agent suggestion"
method: POST
path: "/v1/agent-suggestions/{id}/apply"
tags: ["Agent Suggestions"]
---

# Apply a pending agent suggestion

`POST /v1/agent-suggestions/{id}/apply`

## 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/agent-suggestions/{id}/apply`
- Auth: one of:
  - API key in header `GREPR-API-KEY`
  - OpenID Connect (`https://grepr-prod.us.auth0.com/.well-known/openid-configuration`)

Re-verifies the suggestion's template-inputs patch against the pipeline's current version and applies it as a new job version, marking the suggestion APPLIED. The resolution is compare-and-set on the pending status: a reviewer who loses a race to another gets 409 rather than overwriting it. Findings mean the pipeline changed since the suggestion was recorded; nothing is applied and the suggestion stays PENDING. Applying restarts the pipeline from a savepoint.

## Path parameters

- `id` string, required

## Response `200`

Suggestion applied, or rejected by verification with findings

- AgentSuggestionApplyResult
  - `appliedJobVersion` integer: The new job version the suggestion was applied as, or absent when it was rejected by verification. Applying restarts the pipeline from a savepoint, so the new version reaches its desired state asynchronously.
  - `findings` ChangeFinding[]: Verification findings that blocked the apply. When present the pipeline is untouched and the suggestion stays PENDING: the pipeline changed since the suggestion was recorded, so the change is no longer safe to apply as-is.
    - `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
  - `suggestion` AgentSuggestion, required
    - `agentId` string
    - `appliedJobVersion` integer
    - `baseJobVersion` integer
    - `createdAt` string, date-time
    - `description` string
    - `id` string
    - `investigationId` string
    - `jobId` string
    - `organizationId` string
    - `reviewedAt` string, date-time
    - `reviewedBy` string
    - `samples` LogEvent[]
      - `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.
    - `status` 'PENDING' | 'APPLIED' | 'REJECTED'
    - `teamIds` string[]
    - `templateInputsPatch` JsonNode: 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.
    - `toolCallId` string
    - `updatedAt` string, date-time

## Other responses

- `401`: Unauthorized
- `404`: Suggestion not found
- `409`: Suggestion is no longer pending

---

[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)