Grepr Agent Suggestions API

openapi: 3.2.0
info:
  title: Grepr Agent Suggestions API
  version: 1.0.0
  description: 'Operations tagged Agent Suggestions across 2 of this provider''s published API definitions: grepr-openapi.json, grepr.json. Each path carries the servers of the definition it was published in.'
tags:
- name: Agent Suggestions
paths:
  /v1/agent-suggestions:
    get:
      description: Returns the organization's agent suggestions, newest first, optionally filtered by pipeline, review status, and proposing agent.
      operationId: list_2
      parameters:
      - in: query
        name: jobId
        schema:
          type: string
      - in: query
        name: status
        schema:
          enum:
          - PENDING
          - APPLIED
          - REJECTED
          type: string
      - in: query
        name: agentId
        schema:
          type: string
      - in: query
        name: page
        schema:
          default: 0
          format: int32
          maximum: 21474836
          minimum: 0
          type: integer
      - in: query
        name: pageSize
        schema:
          default: 25
          format: int32
          maximum: 100
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSuggestionsList'
          description: Suggestions retrieved successfully
        '401':
          description: Unauthorized
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: List agent suggestions
      tags:
      - Agent Suggestions
  /v1/agent-suggestions/{id}:
    get:
      description: Returns one agent suggestion, including the template-inputs patch, the job version it was proposed against, and the sample events it was verified with.
      operationId: get_2
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSuggestion'
          description: Suggestion retrieved successfully
        '401':
          description: Unauthorized
        '404':
          description: Suggestion not found
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Get an agent suggestion
      tags:
      - Agent Suggestions
  /v1/agent-suggestions/{id}/apply:
    post:
      description: '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.'
      operationId: apply
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSuggestionApplyResult'
          description: Suggestion applied, or rejected by verification with findings
        '401':
          description: Unauthorized
        '404':
          description: Suggestion not found
        '409':
          description: Suggestion is no longer pending
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Apply a pending agent suggestion
      tags:
      - Agent Suggestions
  /v1/agent-suggestions/{id}/reject:
    post:
      description: Marks a pending suggestion REJECTED, recording the reviewer. Returns 409 when the suggestion was already resolved by another reviewer.
      operationId: reject
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSuggestion'
          description: Suggestion rejected successfully
        '401':
          description: Unauthorized
        '404':
          description: Suggestion not found
        '409':
          description: Suggestion is no longer pending
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Reject a pending agent suggestion
      tags:
      - Agent Suggestions
components:
  schemas:
    JsonNode:
      description: 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.
      type: object
    ChangeFinding:
      description: 'Verification findings that blocked the change. When present the pipeline is untouched: fix the findings and submit again.'
      properties:
        code:
          enum:
          - 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
          type: string
        details:
          additionalProperties:
            type: string
          type: object
        message:
          type: string
        sampleId:
          type: string
      type: object
    AgentSuggestionsList:
      properties:
        hasMore:
          type: boolean
        limit:
          format: int32
          type: integer
        start:
          format: int32
          type: integer
        suggestions:
          $ref: '#/components/schemas/ItemsCollectionAgentSuggestion'
      type: object
    LogEvent:
      description: A log event.
      properties:
        attributes:
          additionalProperties:
            $ref: '#/components/schemas/Any'
          description: Attributes associated with the event, a map from attribute name to attribute value, which may be a nested map or list.
          type: object
        eventTimestamp:
          description: Event timestamp that is in the record. Milliseconds from epoch.
          format: int64
          type: integer
        id:
          description: Id of the event.
          example: 034JA9FJ
          type: string
        message:
          description: The log message.
          example: This is a log message.
          type: string
        receivedTimestamp:
          description: Timestamp when the event was received by Grepr. Milliseconds from epoch.
          format: int64
          type: integer
        severity:
          description: The log severity. Higher numbers mean higher severity, following the OTel format 1-24.
          format: int32
          type: integer
        tags:
          additionalProperties:
            description: Tags associated with the event, a map from tag name to set of tag values.
            items:
              description: Tags associated with the event, a map from tag name to set of tag values.
              type: string
            type: array
            uniqueItems: true
          description: Tags associated with the event, a map from tag name to set of tag values.
          type: object
      required:
      - eventTimestamp
      - id
      - receivedTimestamp
      type: object
    AgentSuggestionApplyResult:
      properties:
        appliedJobVersion:
          description: 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.
          format: int64
          type: integer
        findings:
          default: []
          description: '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.'
          items:
            $ref: '#/components/schemas/ChangeFinding'
          type: array
        suggestion:
          $ref: '#/components/schemas/AgentSuggestion'
      required:
      - suggestion
      type: object
    AgentSuggestion:
      properties:
        agentId:
          type: string
        appliedJobVersion:
          format: int64
          type: integer
        baseJobVersion:
          format: int64
          type: integer
        createdAt:
          format: date-time
          type: string
        description:
          type: string
        id:
          type: string
        investigationId:
          type: string
        jobId:
          type: string
        organizationId:
          type: string
        reviewedAt:
          format: date-time
          type: string
        reviewedBy:
          type: string
        samples:
          items:
            $ref: '#/components/schemas/LogEvent'
          type: array
        status:
          enum:
          - PENDING
          - APPLIED
          - REJECTED
          type: string
        teamIds:
          items:
            type: string
          type: array
        templateInputsPatch:
          $ref: '#/components/schemas/JsonNode'
        toolCallId:
          type: string
        updatedAt:
          format: date-time
          type: string
      type: object
    ItemsCollectionAgentSuggestion:
      properties:
        items:
          default: []
          items:
            $ref: '#/components/schemas/AgentSuggestion'
          type: array
      type: object
    Any:
      description: A value that can be a primitive (String or number), a list, or a map.
      example:
      - 12
      - a
      - b: 1
      - - 1
        - 2
        - 3
  securitySchemes:
    grepr-api-key:
      in: header
      name: GREPR-API-KEY
      type: apiKey
    grepr-oidc:
      bearerFormat: JWT
      openIdConnectUrl: https://grepr-prod.us.auth0.com/.well-known/openid-configuration
      type: openIdConnect
x-refined-from:
- grepr-openapi.json
- grepr.json
x-tagGroups:
- name: Integrations
  tags:
  - Grepr-hosted Data Warehouse Integration
  - External S3 Data Warehouse Integration
  - Datadog Integration
  - New Relic Integration
  - Splunk Integration
  - Sumo Logic Integration
  - OpenTelemetry Integration
- name: Pipelines
  tags:
  - Jobs
  - Templates
  - Datasets
  - Status Metrics
  - External Triggers
  - Job Actions
  - Triggers
- name: Pipeline Components
  tags:
  - Operations
  - Transforms
  - Sources
  - Sinks
- name: Administration
  tags:
  - Users
  - Teams
  - Roles
  - Permission
  - Invitations
  - Activity Logs
- name: Organization
  tags:
  - Organizations
  - Access Configuration
  - Grepr API Key
  - Service Accounts
  - Signup
- name: Query & Analysis
  tags:
  - Job Anomalies
  - Grok Parsing
  - Query Parsing
  - Validation
- name: System
  tags:
  - Manifest