Grepr Investigations API

openapi: 3.2.0
info:
  title: Grepr Investigations API
  version: 1.0.0
  description: 'Operations tagged Investigations 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: Investigations
paths:
  /v1/investigations:
    post:
      description: Triggers an agent investigation with optional free-form context and returns the new investigation id. The investigation is queued and runs asynchronously once the agent has a free concurrency slot. With issueId, a person hands the agent that issue, which becomes the investigation's subject and records the handoff in its history.
      operationId: start
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartInvestigationRequest'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartInvestigationResponse'
          description: Investigation queued
        '400':
          description: An invalid continuation, or a handoff that is also a continuation or to an agent with no issue tools (a handoff's refusals carry an issue error body)
        '401':
          description: Unauthorized
        '403':
          description: No permission to run investigations, or a handoff by anyone but a person, by a person who may not edit the issue, or to an agent that may not view and edit it
        '404':
          description: Agent not found, or the handed issue doesn't exist or the caller can't see it
        '409':
          description: The agent is paused or the continued investigation is still active, or a handoff of a closed issue or to an agent a person removed from it
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartInvestigationRejectedResponse'
          description: The agent is at its maximum concurrent investigations and its concurrency-limit policy discards new work instead of queueing it (the response carries the id of the recorded DISCARDED investigation), or the agent's or its LLM integration's max tokens are reached (the response carries a code and message).
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Start an investigation
      tags:
      - Investigations
  /v1/investigations/cancel:
    post:
      description: Marks eligible investigations as CANCELLING in one organization-scoped request. Cancellation is completed asynchronously.
      operationId: batchCancelInvestigations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCancelInvestigationsRequest'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCancelInvestigationsResponse'
          description: Cancellation requests recorded
        '400':
          description: The request is empty or contains more than 500 ids
        '401':
          description: Unauthorized
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Cancel multiple investigations
      tags:
      - Investigations
  /v1/investigations/cancel-all:
    post:
      description: Marks every queued, running, and paused investigation of every agent in the organization as CANCELLING in one request. Cancellation is completed asynchronously. With pause=true, every active agent is paused in the same transaction so none starts new investigations; resume each agent to undo it.
      operationId: cancelAllInvestigations
      parameters:
      - description: Also pause every active agent in the organization
        in: query
        name: pause
        schema:
          default: false
          type: boolean
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelAllInvestigationsResponse'
          description: Cancellation requests recorded
        '401':
          description: Unauthorized
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Cancel every active investigation in the organization
      tags:
      - Investigations
  /v1/investigations/cancellable-counts:
    get:
      description: Returns how many investigations across every agent in the organization are queued, running, or paused, and so would be cancelled by cancel-all, and whether the caller is authorized to call cancel-all.
      operationId: countCancellableInvestigations
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancellableInvestigationsResponse'
          description: Counts retrieved
        '401':
          description: Unauthorized
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Count the organization's active investigations
      tags:
      - Investigations
  /v1/investigations/{investigationId}/cancel:
    post:
      description: Durably marks an eligible investigation as CANCELLING and returns 202. An asynchronous reconciler cancels its workflow, if one exists, and it then finalizes as CANCELLED.
      operationId: cancel_1
      parameters:
      - in: path
        name: investigationId
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Cancel requested
        '401':
          description: Unauthorized
        '404':
          description: Investigation not found
        '409':
          description: Investigation is already finished
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Cancel an investigation
      tags:
      - Investigations
  /v1/investigations/{investigationId}/chat:
    post:
      description: Creates a new chat seeded with a copy of the investigation's transcript and returns its chat id, then durably requests the investigation's cancellation so it does not keep running alongside the chat. Each call opens a separate chat.
      operationId: chat
      parameters:
      - in: path
        name: investigationId
        required: true
        schema:
          type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChatResponse'
          description: Chat opened
        '401':
          description: Unauthorized
        '404':
          description: Investigation not found
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Open an investigation as a chat
      tags:
      - Investigations
  /v1/investigations/{investigationId}/resume:
    post:
      description: Resumes a stopped (resumable) investigation in place. A non-blank message is appended as a new user turn; an empty body continues the agent with no added input.
      operationId: resume
      parameters:
      - in: path
        name: investigationId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeInvestigationRequest'
      responses:
        '202':
          description: Resume requested
        '401':
          description: Unauthorized
        '404':
          description: Investigation not found
        '409':
          description: Investigation is not resumable
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Resume a stopped investigation
      tags:
      - Investigations
  /v1/investigations/{investigationId}/stop:
    post:
      description: Durably marks a running investigation as STOPPING and returns 202. An asynchronous reconciler signals the workflow, which pauses at its next turn boundary and records STOPPED; it can then be resumed with a message.
      operationId: stop_1
      parameters:
      - in: path
        name: investigationId
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Stop requested
        '401':
          description: Unauthorized
        '404':
          description: Investigation not found
        '409':
          description: Investigation is not running
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Stop a running investigation
      tags:
      - Investigations
  /v1/investigations/{investigationId}/transcript:
    get:
      description: Returns the investigation's status, timestamps, summary, and recorded actions. Read transcript content from the cursor-paged turns endpoint.
      operationId: transcript
      parameters:
      - in: path
        name: investigationId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvestigationTranscript'
          description: Investigation metadata retrieved successfully
        '401':
          description: Unauthorized
        '404':
          description: Investigation not found
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Get investigation metadata
      tags:
      - Investigations
  /v1/investigations/{investigationId}/turns:
    get:
      description: Returns journalled turns after the given sequence, oldest first.
      operationId: turns_1
      parameters:
      - in: path
        name: investigationId
        required: true
        schema:
          type: string
      - in: query
        name: afterSeq
        schema:
          default: -1
          format: int32
          minimum: -1
          type: integer
      - in: query
        name: pageSize
        schema:
          default: 50
          format: int32
          maximum: 100
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscriptTurnsList'
          description: Turns retrieved successfully
        '401':
          description: Unauthorized
        '404':
          description: Investigation not found
      security:
      - grepr-api-key: []
      - grepr-oidc: []
      summary: Stream an investigation's transcript turns by sequence cursor
      tags:
      - Investigations
components:
  schemas:
    StartInvestigationRequest:
      description: Request body for the manual-trigger endpoint. The engineer's user identity is taken from the request's auth context, not the body.
      properties:
        agentId:
          description: TSID of the agent to investigate.
          type: string
        issueId:
          description: 'When set, hands the agent this issue (its TSID): the run''s subject, which its first message holds and whose history records the handoff. Only a person may hand off an issue, and a handoff can''t be a continuation. `null` for a plain run.'
          type: string
        next:
          description: 'With `issueId`, true to have the agent work on the issue next: the run starts ahead of the agent''s other queued runs, without stopping a running one. Allowed only with `issueId`; `null` or false for the usual place in the queue.'
          type: boolean
        parentInvestigationId:
          description: When set, seeds the new investigation from this parent's journalled transcript — a continuation; the parent must belong to `agentId`. `null` for a fresh investigation.
          type: string
        userProvidedContext:
          description: Free-form context for the agent's first turn, or `null`.
          type: string
      required:
      - agentId
      type: object
    TranscriptTurnsList:
      properties:
        hasMore:
          type: boolean
        turns:
          items:
            $ref: '#/components/schemas/TranscriptTurn'
          type: array
      type: object
    BatchCancelInvestigationsResponse:
      properties:
        cancelling:
          items:
            type: string
          type: array
        skipped:
          items:
            $ref: '#/components/schemas/SkippedInvestigation'
          type: array
      type: object
    BatchCancelInvestigationsRequest:
      properties:
        investigationIds:
          items:
            type: string
          maxItems: 500
          minItems: 1
          type: array
      required:
      - investigationIds
      type: object
    StartInvestigationRejectedResponse:
      oneOf:
      - $ref: '#/components/schemas/StartInvestigationResponse'
      - $ref: '#/components/schemas/StartInvestigationErrorResponse'
      type: object
    StartInvestigationErrorResponse:
      properties:
        code:
          format: int32
          type: integer
        message:
          type: string
      type: object
    InvestigationTranscript:
      properties:
        actions:
          items:
            $ref: '#/components/schemas/InvestigationAction'
          type: array
        agentId:
          type: string
        createdAt:
          format: date-time
          type: string
        endedAt:
          format: date-time
          type: string
        investigationId:
          type: string
        startedAt:
          format: date-time
          type: string
        status:
          enum:
          - QUEUED
          - RUNNING
          - STOPPING
          - CANCELLING
          - STOPPED
          - COMPLETED
          - FAILED
          - CANCELLED
          - DISCARDED
          type: string
        summary:
          type: string
      type: object
    CreateChatResponse:
      properties:
        chatId:
          type: string
      type: object
    ResumeInvestigationRequest:
      properties:
        text:
          type: string
      type: object
    TranscriptTurn:
      properties:
        messages:
          items:
            $ref: '#/components/schemas/TranscriptMessage'
          type: array
        seq:
          format: int32
          type: integer
      type: object
    TranscriptToolCall:
      properties:
        argumentsJson:
          type: string
        id:
          type: string
        name:
          type: string
      type: object
    CancellableInvestigationsResponse:
      properties:
        canCancel:
          type: boolean
        counts:
          $ref: '#/components/schemas/CancellableInvestigationCounts'
      required:
      - canCancel
      - counts
      type: object
    CancelAllInvestigationsResponse:
      properties:
        cancelling:
          format: int32
          type: integer
        paused:
          format: int32
          type: integer
      required:
      - cancelling
      - paused
      type: object
    InvestigationAction:
      properties:
        description:
          type: string
        toolCallId:
          type: string
        toolName:
          type: string
        url:
          type: string
      type: object
    StartInvestigationResponse:
      properties:
        investigationId:
          type: string
      type: object
    SkippedInvestigation:
      properties:
        investigationId:
          type: string
        reason:
          enum:
          - NOT_FOUND
          - ALREADY_FINISHED
          type: string
      type: object
    TranscriptMessage:
      properties:
        durationNanos:
          format: int64
          type: integer
        id:
          type: string
        role:
          enum:
          - SYSTEM
          - TRIGGER_SIGNAL
          - USER
          - ASSISTANT
          - TOOL_RESULT
          - KNOWN_ISSUES
          type: string
        startedAt:
          format: date-time
          type: string
        text:
          type: string
        timestamp:
          format: date-time
          type: string
        toolCallId:
          type: string
        toolCalls:
          items:
            $ref: '#/components/schemas/TranscriptToolCall'
          type: array
        toolName:
          type: string
      type: object
    CancellableInvestigationCounts:
      properties:
        paused:
          format: int32
          type: integer
        queued:
          format: int32
          type: integer
        running:
          format: int32
          type: integer
      required:
      - paused
      - queued
      - running
      type: object
  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