openapi: 3.0.1
info:
  title: Korrel8r REST API
  description: Generate graphs showing correlations between resources and observability signals in a cluster.
  contact:
    name: Project Korrel8r
    url: https://github.com/korrel8r/korrel8r
  license:
    name: Apache 2.0
    url: https://github.com/korrel8r/korrel8r/blob/main/LICENSE
  version: v1alpha1
externalDocs:
  url: https://korrel8r.github.io/korrel8r/
  description: Korrel8r User Guide
servers:
  - url: /api/v1alpha1
tags:
  - name: console
    description: >
      Korrel8r can act as a bridge between a GUI console and an AI agent.
      The agent uses Korrel8r's MCP API to discover what is displayed in the console,
      and to send new data to update what is displayed.
      The console uses the /console REST APIs to provide information about the current display,
      and to accept updates from the agent to change the display.

paths:
  /config:
    put:
      summary: Change configuration settings at runtime.
      description: >
        Modify selected configuration settings (e.g. log verbosity) on a running service.
      operationId: setConfig
      tags: [configure]
      parameters:
        - name: verbose
          description: Verbose level for logging.
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 10
      responses:
        "200":
          description: OK

  /domains:
    get:
      summary: Get the list of correlation domains.
      description: >
        Returns a list of Korrel8r domains and the stores configured for each domain.
      operationId: listDomains
      tags: [query]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                x-go-type-skip-optional-pointer: true
                items:
                  $ref: "#/components/schemas/Domain"
        "400":
          description: invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: result not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /domain/{domain}/classes:
    get:
      summary: Get the list of classes for a domain.
      description: >
        Returns a list of class names for the specified domain.
      operationId: listDomainClasses
      tags: [query]
      parameters:
        - name: domain
          in: path
          required: true
          description: Name of the domain to list classes for
          schema:
            type: string
          example: k8s
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                x-go-type-skip-optional-pointer: true
                items:
                  type: string
                  description: Class name (without domain prefix)
                example: ["Pod", "Service", "Deployment"]
        "400":
          description: invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: domain not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /graphs/goals:
    post:
      summary: Create a correlation graph from start objects to goal queries.
      description: >
        Specify a set of start objects, as queries or serialized objects, and a goal class.
        Returns a graph containing all paths leading from a start object to a goal object.
      operationId: graphGoals
      tags: [correlate]
      parameters:
        - $ref: "#/components/parameters/GraphOptions"
      requestBody:
        description: Search from start to goal classes.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Goals"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Graph"
        "400":
          description: invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: result not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-codegen-request-body-name: request
  /graphs/neighbors:
    post:
      summary: Create a neighborhood graph around a start object to a given depth.
      description: >
        Specify a set of start objects, as queries or serialized objects,
        and a depth for the neighborhood search.
        Returns a graph of all paths with depth or less edges leading from start objects.
      operationId: graphNeighbors
      tags: [correlate]
      parameters:
        - $ref: "#/components/parameters/GraphOptions"
      requestBody:
        description: Search from start for neighbors.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Neighbors"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Graph"
        "400":
          description: invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: result not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-codegen-request-body-name: request

  # DEPRECATED - alternate spelling.
  /graphs/neighbours:
    post:
      summary: Create a neighborhood graph around a start object to a given depth.
      description: >
        Specify a set of start objects, as queries or serialized objects,
        and a depth for the neighborhood search.
        Returns a graph of all paths with depth or less edges leading from start objects.
      operationId: graphNeighbours
      tags: [correlate]
      parameters:
        - $ref: "#/components/parameters/GraphOptions"
      requestBody:
        description: Search from start for neighbors.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Neighbors"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Graph"
        "400":
          description: invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: result not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-codegen-request-body-name: request

  /lists/goals:
    post:
      summary: Create a list of goal nodes related to a starting point.
      description: >
        Specify a set of start objects, as queries or serialized objects, and a goal class.
        Returns a list of all objects of the goal class that can be reached from a start object.
      operationId: listGoals
      tags: [correlate]
      requestBody:
        description: search from start to goal classes
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Goals"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                x-go-type-skip-optional-pointer: true
                items:
                  $ref: "#/components/schemas/Node"
        "400":
          description: invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: result not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-codegen-request-body-name: request
  /objects:
    get:
      summary: Execute a query, returns a list of JSON objects.
      description: >
        Execute a single Korrel8r 'query' and return the list of serialized objects found.
        Does not perform any correlation actions.
      operationId: objects
      tags: [query]
      parameters:
        - name: query
          description: Query string.
          in: query
          required: true
          schema:
            $ref: "#/components/schemas/Query"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                x-go-type-skip-optional-pointer: true
                items:
                  type: object
                  additionalProperties: true
        "400":
          description: invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: result not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /console:
    put:
      summary: Make console state available to an agent.
      description: >
        Put the current state of the console so it can be retrieved by an agent via the MCP API.
      tags: [console]
      operationId: setConsole
      requestBody:
        description: Parameters for the updated console display.
        content:
          text/json:
            schema:
              $ref: "#/components/schemas/Console"
        required: true
      responses:
        "200":
          description: Console display updated successfully
        "400":
          description: invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      x-codegen-request-body-name: request

  /console/events:
    get:
      summary: SSE event stream of console display updates from an agent.
      description: >
        Server-sent event (SSE) stream delivering console display updates.
        Events are triggered by an agent using the MCP API to update the console.
      tags: [console]
      operationId: consoleEvents
      responses:
        "200":
          description: Stream of console display updates.
          content:
            text/event-stream:
              itemSchema:
                # Reference a schema that defines the structure of each individual event
                $ref: "#/components/schemas/Console"

components:
  schemas:
    Query:
      type: string
      pattern: "[^:]+:[^:]+:[^:]+"
      description: >
        Represents a request to retrieve data for a particular Class.
        It has 3 colon-separated parts: DOMAIN:CLASS:SELECTOR.
        DOMAIN: name of a domain (e.g. k8s, log, metric, alert, trace, netflow).
        CLASS: name of a class in the domain (e.g. Pod, application, metric, alert, span, network).
        SELECTOR: domain-specific query string, syntax varies by domain:
        k8s uses JSON (e.g. {"namespace":"default","name":"my-pod"}),
        log uses LogQL or JSON (e.g. {"namespace":"default"}),
        metric uses PromQL (e.g. kube_pod_info{namespace="default"}),
        alert uses JSON labels (e.g. {"alertname":"KubePodCrashLooping"}),
        trace uses TraceQL (e.g. {resource.k8s.namespace.name="default"}),
        netflow uses LogQL labels (e.g. {SrcK8S_Namespace="default"}).
      example: "k8s:Pod:{namespace: foo, name: bar, labels: { a: b }, fields: { c: d }}"
      x-go-type-skip-optional-pointer: true

    Class:
      type: string
      pattern: "[^:]+:[^:]+"
      description: >
        Full name of a class of objects: DOMAIN:CLASS.
        DOMAIN: name of a domain (e.g. k8s, log, metric, alert, trace, netflow).
        CLASS: name within the domain.
        Examples: k8s:Pod, k8s:Deployment.apps, log:application, metric:metric, alert:alert, trace:span, netflow:network.
      example: "trace:span"
      x-go-type-skip-optional-pointer: true

    Constraint:
      description: Constrains the objects that will be included in search results.
      type: object
      x-go-type: korrel8r.Constraint
      properties:
        start:
          type: string
          description: Ignore objects with timestamps before this start time.
          format: date-time
        end:
          type: string
          description: Ignore objects with timestamps after this end time.
          format: date-time
          example: "2017-07-21T17:32:28.1341231Z"
        limit:
          type: integer
          description: Limit total number of objects per query.
        timeout:
          description: DEPRECATED store calls are cancelled with the request.
          allOf:
            - $ref: "#/components/schemas/Duration"

    Duration:
      type: string
      description: >
        The duration string is a sequence of decimal numbers, each with optional
        fraction and a unit suffix. Valid time units are: ns, us (or µs), ms, s, m, h.
      format: duration
      example: 2h45m
      x-go-type: time.Duration

    Domain:
      type: object
      description: Domain configuration information.
      required: [name]
      properties:
        name:
          type: string
          description: Name of the domain.
        description:
          type: string
          description: Brief description of the domain.
          x-go-type-skip-optional-pointer: true
        stores:
          type: array
          description: Stores configured for the domain.
          items:
            $ref: "#/components/schemas/Store"
          x-go-type-skip-optional-pointer: true

    Edge:
      type: object
      required: [start, goal]
      properties:
        start:
          description: Class name of the start node.
          allOf:
            - $ref: "#/components/schemas/Class"
        goal:
          description: Class name of the goal node.
          allOf:
            - $ref: "#/components/schemas/Class"
        rules:
          type: array
          x-go-type-skip-optional-pointer: true
          x-omitempty: true
          description: Set of rules followed along this edge.
          items:
            $ref: "#/components/schemas/Rule"
      description: Directed edge in the result graph, from Start to Goal classes.

    Error:
      description: Error result containing an error message.
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message.

    Goals:
      type: object
      required: [goals, start]
      properties:
        goals:
          type: array
          x-go-type-skip-optional-pointer: true
          description: >
            Goal classes for correlation in "domain:class" format.
            The search follows all paths from start to these classes.
            Example: ["log:application"] or ["alert:alert", "metric:metric"].
          example: ["k8s:Pod"]
          items:
            $ref: "#/components/schemas/Class"
          x-oapi-codegen-extra-tags:
            jsonschema: "Goal classes in domain:class format, e.g. log:application, alert:alert"
        start:
          description: "Starting point for the correlation search."
          allOf:
            - $ref: "#/components/schemas/Start"
          x-oapi-codegen-extra-tags:
            jsonschema: "Starting point for the correlation search"
      description: >
        Parameters for a goal-directed correlation search.
        Finds paths from start objects to the specified goal classes.

    Graph:
      type: object
      properties:
        edges:
          description: List of graph edges.
          type: array
          x-go-type-skip-optional-pointer: true
          items:
            $ref: "#/components/schemas/Edge"
        nodes:
          description: List of graph nodes.
          type: array
          x-go-type-skip-optional-pointer: true
          items:
            $ref: "#/components/schemas/Node"
      description: Graph resulting from a correlation search.

    Neighbors:
      type: object
      required: [depth, start]
      properties:
        depth:
          type: integer
          description: >
            Maximum number of correlation steps to follow from the start.
            Depth 1 returns only direct correlations, depth 2 includes correlations of correlations, etc.
          x-oapi-codegen-extra-tags:
            jsonschema: "Max correlation depth (1 = direct correlations only)"
        start:
          description: "Starting point for the correlation search."
          allOf:
            - $ref: "#/components/schemas/Start"
          x-oapi-codegen-extra-tags:
            jsonschema: "Starting point for the correlation search"
      description: >
        Parameters for a neighborhood correlation search.
        Finds all correlated objects reachable within the specified depth from start objects.

    Node:
      description: Node in the result graph, contains results for a single class.
      type: object
      required: [class]
      properties:
        class:
          type: string
          description: Full class name
        queries:
          type: array
          x-go-type-skip-optional-pointer: true
          description: Queries yielding results for this class.
          items:
            $ref: "#/components/schemas/QueryCount"
        count:
          type: integer
          description: Number of results for this class, after de-duplication.
        result:
          description: Serialized result contents, may be large.
          type: array
          x-go-type-skip-optional-pointer: true
          items:
            $ref: "#/components/schemas/Object"

    QueryCount:
      description: Query with number of results.
      type: object
      required: [query]
      properties:
        count:
          description: Number of results, omitted if the query was not executed.
          type: integer
        query:
          description: Query for correlation data.
          allOf:
            - $ref: "#/components/schemas/Query"

    Rule:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Name is an optional descriptive name.
        queries:
          type: array
          x-go-type-skip-optional-pointer: true
          description: Queries generated while following this rule.
          items:
            $ref: "#/components/schemas/QueryCount"
      description: Rule is a correlation rule with a list of queries and results counts found during navigation.

    Object:
      description: Data object serialized as JSON.
      type: object
      additionalProperties: true
      x-go-type: json.RawMessage

    Start:
      type: object
      properties:
        class:
          description: >
            Class of starting objects. Required when using 'objects' to specify the class of the serialized objects.
            Optional with 'queries' since the class is embedded in each query string.
          allOf:
            - $ref: "#/components/schemas/Class"
          x-go-type-skip-optional-pointer: true
          x-oapi-codegen-extra-tags:
            jsonschema: "Optional class of start objects in domain:class format, e.g. k8s:Pod"
        constraint:
          allOf:
            - $ref: "#/components/schemas/Constraint"
          description: >
            Optional time and count constraints on the objects returned by queries.
          x-oapi-codegen-extra-tags:
            jsonschema: "Optional time/count constraints on returned objects"
        objects:
          description: >
            Start objects serialized as JSON. Requires 'class' to identify the object type.
            Alternative to 'queries' when you already have the objects.
          type: array
          x-go-type-skip-optional-pointer: true
          items:
            $ref: "#/components/schemas/Object"
          x-oapi-codegen-extra-tags:
            jsonschema: "Start objects as JSON (requires class field). Alternative to queries."
        queries:
          type: array
          x-go-type-skip-optional-pointer: true
          description: >
            Queries for starting objects in "domain:class:selector" format.
            This is the most common way to specify a starting point.
            Example: ["k8s:Pod:{\"namespace\":\"default\",\"name\":\"my-pod\"}"]
          items:
            $ref: "#/components/schemas/Query"
          x-oapi-codegen-extra-tags:
            jsonschema: "Queries in domain:class:selector format, e.g. k8s:Pod:{namespace: default}"
      description: >
        Identifies the starting point for a correlation search.
        Provide either 'queries' (most common) or 'class' + 'objects'.

    Store:
      type: object
      additionalProperties:
        type: string
      description: Store is a map string keys and values used to connect to a store.

    Console:
      description: >
        State of the user's graphical console display (e.g. OpenShift web console).
        The query field indicates what data the console is showing.
        The search field optionally specifies a correlation search for the troubleshooting panel.
      type: object
      properties:
        query:
          description: "Query the console is displaying."
          allOf:
            - $ref: "#/components/schemas/Query"
          x-oapi-codegen-extra-tags:
            jsonschema: "Query the console is displaying, in domain:class:selector format"
        search:
          description: "Optional correlation search for the troubleshooting panel."
          allOf:
            - $ref: "#/components/schemas/Search"
          x-oapi-codegen-extra-tags:
            jsonschema: "Optional correlation search for the troubleshooting panel"

    Search:
      description: >
        Correlation search parameters for the console troubleshooting panel.
        Set exactly one of 'goals' (targeted search to specific classes) or 'neighbors' (open-ended exploration to a depth).
      type: object
      properties:
        goals:
          description: "Goal-directed search parameters (mutually exclusive with neighbors)."
          allOf:
            - $ref: "#/components/schemas/Goals"
          x-oapi-codegen-extra-tags:
            jsonschema: "Goal-directed search parameters (mutually exclusive with neighbors)"
        neighbors:
          description: "Neighborhood search parameters (mutually exclusive with goals)."
          allOf:
            - $ref: "#/components/schemas/Neighbors"
          x-oapi-codegen-extra-tags:
            jsonschema: "Neighborhood search parameters (mutually exclusive with goals)"

  parameters:
    GraphOptions:
      name: options
      description: Options controlling the form of the returned graph.
      in: query
      style: form
      explode: true
      schema:
        type: object
        properties:
          rules:
            description: If true include rule names in graph edges.
            type: boolean
          results:
            description: If true include full JSON results with each Query.
            type: boolean
          errors:
            description: if true include non-fatal error messages.
            type: boolean