> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Runbook

> Returns one Runbook resource

<ParamField path="name" type="string" required>
  Runbook name (e.g., `oomkill-standard`)
</ParamField>

<ParamField query="namespace" type="string" default="default">
  Namespace of the runbook. Defaults to `default` (other namespaces are not searched).
</ParamField>

`spec` carries the runbook in the same shape as [List Runbooks](/reference/api/list-runbooks); `resourceMeta` carries its Kubernetes metadata (uid, labels, annotations). There is no `status`.

<ResponseExample>
  ```json Response 200 theme={"system"}
  {
    "apiVersion": "v1",
    "kind": "Runbook",
    "spec": {
      "name": "oomkill-standard",
      "namespace": "production",
      "description": "Standard remediation for OOMKill: raise the memory limit and restart the Deployment",
      "trigger": {
        "signalType": "oom_kill",
        "severity": "high",
        "resourceKind": "Deployment"
      },
      "steps": [
        {
          "name": "raise-memory-limit",
          "action": "AdjustResources",
          "description": "Raise the container memory limit",
          "params": {
            "memory_limit": "1Gi"
          }
        },
        {
          "name": "restart",
          "action": "RestartDeployment",
          "description": "Restart pods to reclaim memory"
        }
      ],
      "maxAttempts": 3,
      "creationTimestamp": "2026-01-10T08:00:00Z"
    },
    "resourceMeta": {
      "name": "oomkill-standard",
      "namespace": "production",
      "uid": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
      "creationTimestamp": "2026-01-10T08:00:00Z"
    }
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json Response 404 theme={"system"}
  {
    "apiVersion": "v1",
    "kind": "Error",
    "error": "Not Found",
    "code": 404,
    "message": "runbook not found: runbooks.platform.chatcli.io \"oomkill-standard\" not found"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /runbooks/{name}
openapi: 3.1.0
info:
  title: ChatCLI AIOps Platform API
  description: >-
    REST API served by the ChatCLI operator — incidents, SLOs, runbooks,
    approvals, postmortems, remediations, AI insights, analytics, audit,
    clusters, federation, policies and health.


    **Where it runs.** The API and the web dashboard share the operator's `api`
    port (default `8090`, Helm value `api.port`, env `CHATCLI_AIOPS_PORT`),
    exposed by the Service `chatcli-operator` in the operator namespace — not by
    an Instance Service. Plain HTTP by default; HTTPS (TLS 1.3) when
    `CHATCLI_AIOPS_TLS_CERT` and `CHATCLI_AIOPS_TLS_KEY` are set. In 1.211.2 and
    earlier only the leader replica listens on 8090.


    **Authentication.** Every `/api/v1/*` call needs the `X-API-Key` header (see
    the `ApiKeyAuth` scheme). Roles are `viewer` < `operator` < `admin`; each
    operation states its minimum role. A role below the minimum gets `403`.


    **Rate limit.** 30 requests per minute per client address (token bucket).
    Exceeding it returns `429` with `Retry-After: 60`. The limit is applied
    before authentication.


    **Envelope.** Lists return `{apiVersion, kind, metadata: {totalCount, page,
    pageSize}, items}`; single resources return `{apiVersion, kind, spec,
    status, resourceMeta}`; errors return `{apiVersion: "v1", kind: "Error",
    error: <HTTP status text>, code, message}`.


    The playground uses **editable server variables** so you can point requests
    at your own operator (for example through `kubectl -n chatcli-system
    port-forward svc/chatcli-operator 8090:8090`).
  version: 1.0.0
  contact:
    name: ChatCLI
    url: https://github.com/diillson/chatcli
  license:
    name: Apache-2.0
    identifier: Apache-2.0
servers:
  - url: '{scheme}://{host}:{port}/{basePath}'
    description: >-
      Self-hosted ChatCLI operator — adjust scheme, host, port and basePath to
      match your deployment.
    variables:
      scheme:
        default: http
        enum:
          - http
          - https
        description: >-
          `https` when the operator runs with CHATCLI_AIOPS_TLS_CERT /
          CHATCLI_AIOPS_TLS_KEY.
      host:
        default: localhost
        description: >-
          Host of the operator API. In-cluster: the Service `chatcli-operator`
          in the operator namespace (e.g.
          `chatcli-operator.chatcli-system.svc`). From a workstation:
          `localhost` with `kubectl port-forward svc/chatcli-operator
          8090:8090`, or your Ingress host.
      port:
        default: '8090'
        description: >-
          API/dashboard port. Default 8090; Helm value `api.port`, env var
          `CHATCLI_AIOPS_PORT`.
      basePath:
        default: api/v1
        description: API base path. Always `api/v1` unless a proxy rewrites it.
security:
  - ApiKeyAuth: []
tags:
  - name: Incidents
    description: >-
      Incidents (Issue CRs): list, fetch, acknowledge, resolve, snooze, timeline
      and remediation views.
  - name: Runbooks
    description: Runbook CRs (list, get, create, update, delete).
  - name: SLOs
    description: ServiceLevelObjective CRs and error budgets.
  - name: Approvals
    description: ApprovalRequest CRs for gated remediations.
  - name: Postmortems
    description: >-
      PostMortem CRs with review, feedback, human-action acknowledgement and
      close.
  - name: Remediations
    description: RemediationPlan CRs and agentic execution history.
  - name: AI Insights
    description: 'AIInsight CRs: AI root-cause analysis and suggested actions per incident.'
  - name: Analytics
    description: >-
      Aggregates computed from the CRs: summary, MTTD, MTTR, trends, top
      resources, remediation stats, compliance, capacity, LLM cost.
  - name: Audit
    description: AuditEvent CRs and JSON export.
  - name: Federation
    description: ClusterRegistration CRs, global status and cross-cluster correlations.
  - name: Policies
    description: >-
      Read-only view of ApprovalPolicy, NotificationPolicy, EscalationPolicy and
      IncidentSLA objects.
  - name: Health
    description: Unauthenticated liveness and readiness endpoints.
paths:
  /runbooks/{name}:
    get:
      tags:
        - Runbooks
      summary: Get Runbook
      description: |-
        Returns one Runbook.

        Minimum role: `viewer`.
      operationId: getRunbook
      parameters:
        - $ref: '#/components/parameters/RunbookName'
        - $ref: '#/components/parameters/NamespaceDefault'
      responses:
        '200':
          description: Runbook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Runbook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    RunbookName:
      name: name
      in: path
      required: true
      description: Runbook name.
      schema:
        type: string
        example: oom-standard
    NamespaceDefault:
      name: namespace
      in: query
      required: false
      description: >-
        Namespace of the object. Defaults to `default` — pass it for objects in
        any other namespace.
      schema:
        type: string
        default: default
  schemas:
    Runbook:
      type: object
      properties:
        apiVersion:
          type: string
          example: v1
        kind:
          type: string
          example: Runbook
        spec:
          $ref: '#/components/schemas/RunbookItem'
        resourceMeta:
          $ref: '#/components/schemas/ResourceMeta'
    RunbookItem:
      type: object
      properties:
        name:
          type: string
        namespace:
          type: string
        description:
          type: string
        trigger:
          $ref: '#/components/schemas/RunbookTrigger'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/RunbookStep'
        maxAttempts:
          type: integer
        creationTimestamp:
          type: string
          format: date-time
    ResourceMeta:
      type: object
      properties:
        name:
          type: string
        namespace:
          type: string
        uid:
          type: string
        creationTimestamp:
          type: string
          format: date-time
        labels:
          type: object
          additionalProperties:
            type: string
        annotations:
          type: object
          additionalProperties:
            type: string
    Error:
      type: object
      required:
        - apiVersion
        - kind
        - error
        - code
        - message
      properties:
        apiVersion:
          type: string
          example: v1
        kind:
          type: string
          example: Error
        error:
          type: string
          description: HTTP status text.
          example: Not Found
        code:
          type: integer
          example: 404
        message:
          type: string
          example: >-
            issue not found: issue "payment-service-oom-1710860400" not found in
            any namespace
    RunbookTrigger:
      type: object
      properties:
        signalType:
          type: string
          example: oom_kill
        severity:
          type: string
          enum:
            - critical
            - high
            - medium
            - low
        resourceKind:
          type: string
          example: Deployment
    RunbookStep:
      type: object
      properties:
        name:
          type: string
        action:
          type: string
          description: >-
            Remediation action type (e.g. `RestartDeployment`,
            `ScaleDeployment`, `AdjustResources`).
          example: RestartDeployment
        description:
          type: string
        params:
          type: object
          additionalProperties:
            type: string
  responses:
    Unauthorized:
      description: >-
        Missing or invalid `X-API-Key`, or no API keys configured (and dev mode
        off)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            apiVersion: v1
            kind: Error
            error: Unauthorized
            code: 401
            message: missing API key in X-API-Key header
    Forbidden:
      description: The key's role is below the operation's minimum role
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            apiVersion: v1
            kind: Error
            error: Forbidden
            code: 403
            message: insufficient permissions
    NotFound:
      description: Object or endpoint not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: More than 30 requests per minute from this client address
      headers:
        Retry-After:
          description: Seconds to wait (always 60).
          schema:
            type: integer
            example: 60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key sent in the `X-API-Key` header. Keys are read from the Secret
        `chatcli-operator-secrets`, key `api-keys` (fallback: ConfigMap
        `chatcli-operator-config`, key `api-keys`) in the operator namespace, as
        a YAML list of `{key, role, description}`; no chart creates it. Roles:
        `viewer` < `operator` < `admin` — any other role string is denied
        everywhere. Changes are picked up within about 30 seconds. With no keys
        configured every `/api/` call returns 401, unless
        `CHATCLI_OPERATOR_DEV_MODE=true`, which grants admin without a key
        (development only).

````