> ## 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.

# Reconhecer Ação Humana

> Registra que uma pessoa executou o acompanhamento exigido por um incidente contido, para que o postmortem possa ser fechado

<ParamField path="name" type="string" required>
  Nome do PostMortem (ex.: `pm-checkout-service-oom-kill-1773871200`)
</ParamField>

<ParamField query="namespace" type="string" default="default">
  Namespace Kubernetes (se omitido, só `default` é pesquisado)
</ParamField>

<ParamField body="acknowledgedBy" type="string">
  Quem executou o acompanhamento. Máximo 253 caracteres. Gravado na annotation `aiops.chatcli.io/human-action-acknowledged-by`.
</ParamField>

<ParamField body="note" type="string">
  Nota livre sobre o que foi feito. Máximo 1024 caracteres. Gravada na annotation `aiops.chatcli.io/human-action-note`.
</ParamField>

## Quando usar

Quando o operator **contém** um incidente (por exemplo, silencia um workload em crash em vez de corrigi-lo), o Issue termina no estado `Contained` e o PostMortem recebe `requiresHumanAction: true` e um `requiredAction` descrevendo o que uma pessoa precisa fazer. Enquanto essa flag estiver ativa e sem reconhecimento, o controller de PostMortem volta qualquer estado `Closed` para `Open`.

Depois de fazer o acompanhamento, chame este endpoint. Ele:

1. Define as annotations `aiops.chatcli.io/human-action-acknowledged: "true"` e `aiops.chatcli.io/human-action-acknowledged-at` (UTC, RFC 3339), além de `-acknowledged-by` e `human-action-note` quando enviados
2. Limpa `status.requiresHumanAction` (`requiredAction` é mantido como histórico)

Em seguida, [feche o postmortem](/pt/reference/api/close-postmortem). O body é opcional. Role mínima: `operator`.

<Note>
  A chamada não restaura o workload; ela só registra que alguém fez isso. Definir a annotation com `kubectl annotate` tem o mesmo efeito no controller (os valores `true`, `True`, `yes`, `ack` e `acknowledged` são aceitos), mas deixa `status.requiresHumanAction` ativo.
</Note>

<ResponseExample>
  ```json Response 200 theme={"system"}
  {
    "apiVersion": "v1",
    "kind": "PostMortem",
    "spec": {
      "name": "pm-checkout-service-oom-kill-1773871200",
      "namespace": "production",
      "issueRef": "checkout-service-oom-kill-1773871200",
      "resource": {
        "kind": "Deployment",
        "name": "checkout-service",
        "namespace": "production"
      },
      "severity": "critical",
      "state": "Open",
      "duration": "12m0s",
      "generatedAt": "2026-03-18T22:12:00Z",
      "creationTimestamp": "2026-03-18T22:12:00Z",
      "requiredAction": "restore the deployment's replicas to the desired count after fixing the root cause (image rollback, config correction, etc.)"
    },
    "status": {
      "name": "pm-checkout-service-oom-kill-1773871200",
      "namespace": "production",
      "issueRef": "checkout-service-oom-kill-1773871200",
      "resource": {
        "kind": "Deployment",
        "name": "checkout-service",
        "namespace": "production"
      },
      "severity": "critical",
      "state": "Open",
      "duration": "12m0s",
      "generatedAt": "2026-03-18T22:12:00Z",
      "creationTimestamp": "2026-03-18T22:12:00Z",
      "requiredAction": "restore the deployment's replicas to the desired count after fixing the root cause (image rollback, config correction, etc.)"
    }
  }
  ```

  ```json Response 400 theme={"system"}
  {
    "apiVersion": "v1",
    "kind": "Error",
    "error": "Bad Request",
    "code": 400,
    "message": "postmortem does not require human action — nothing to acknowledge"
  }
  ```

  ```json Response 409 theme={"system"}
  {
    "apiVersion": "v1",
    "kind": "Error",
    "error": "Conflict",
    "code": 409,
    "message": "postmortem was modified concurrently, please retry"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /postmortems/{name}/ack-human-action
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:
  /postmortems/{name}/ack-human-action:
    post:
      tags:
        - Postmortems
      summary: Acknowledge required human action
      description: >-
        Acknowledges that the human follow-up for a Contained incident has been
        done (rollback, config fix, replicas restored). Sets the annotations
        `aiops.chatcli.io/human-action-acknowledged=true` and
        `aiops.chatcli.io/human-action-acknowledged-at`, plus
        `...-acknowledged-by` and `aiops.chatcli.io/human-action-note` when
        given, then clears `status.requiresHumanAction` so the PostMortem can be
        closed. Returns 400 when the PostMortem does not require human action.


        Minimum role: `operator`.
      operationId: ackPostmortemHumanAction
      parameters:
        - $ref: '#/components/parameters/PostMortemName'
        - $ref: '#/components/parameters/NamespaceDefault'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                acknowledgedBy:
                  type: string
                  maxLength: 253
                  description: Who performed the required action.
                  example: sre-team
                note:
                  type: string
                  maxLength: 1024
                  description: Free-text note describing the action taken.
                  example: Rolled back to v1.2.3 and scaled replicas back to 3.
            example:
              acknowledgedBy: sre-team
              note: Rolled back to v1.2.3 and scaled replicas back to 3.
      responses:
        '200':
          description: >-
            Human action acknowledged. The response has `spec` and `status` but
            no `resourceMeta`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMortem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    PostMortemName:
      name: name
      in: path
      required: true
      description: PostMortem name.
      schema:
        type: string
        example: pm-payment-service-oom-1710860400
    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:
    PostMortem:
      type: object
      properties:
        apiVersion:
          type: string
          example: v1
        kind:
          type: string
          example: PostMortem
        spec:
          $ref: '#/components/schemas/PostMortemItem'
        status:
          $ref: '#/components/schemas/PostMortemItem'
        resourceMeta:
          $ref: '#/components/schemas/ResourceMeta'
    PostMortemItem:
      type: object
      properties:
        name:
          type: string
        namespace:
          type: string
        issueRef:
          type: string
        resource:
          $ref: '#/components/schemas/ResourceRef'
        severity:
          type: string
        state:
          type: string
          enum:
            - Open
            - InReview
            - Closed
        summary:
          type: string
        rootCause:
          type: string
        impact:
          type: string
        duration:
          type: string
        lessonsLearned:
          type: array
          items:
            type: string
        preventionActions:
          type: array
          items:
            type: string
        timeline:
          type: array
          items:
            $ref: '#/components/schemas/TimelineItem'
        actionsExecuted:
          type: array
          items:
            $ref: '#/components/schemas/ActionRecord'
        feedback:
          $ref: '#/components/schemas/PostMortemFeedback'
        generatedAt:
          type: string
          format: date-time
        reviewedAt:
          type: string
          format: date-time
        creationTimestamp:
          type: string
          format: date-time
        requiresHumanAction:
          type: boolean
          description: >-
            `status.requiresHumanAction`: the parent Issue was only Contained.
            Closing is reverted until the human action is acknowledged.
        requiredAction:
          type: string
          description: '`status.requiredAction`.'
        chaosInduced:
          type: boolean
          description: >-
            True when the PostMortem carries the label
            `platform.chatcli.io/source=chaos-experiment`.
        chaosExperiment:
          type: string
    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
    ResourceRef:
      type: object
      properties:
        kind:
          type: string
          example: Deployment
        name:
          type: string
        namespace:
          type: string
    TimelineItem:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          example: detected
        detail:
          type: string
    ActionRecord:
      type: object
      properties:
        action:
          type: string
        params:
          type: object
          additionalProperties:
            type: string
        result:
          type: string
        detail:
          type: string
        timestamp:
          type: string
          format: date-time
    PostMortemFeedback:
      type: object
      properties:
        overrideRootCause:
          type: string
        remediationAccuracy:
          type: integer
          minimum: 1
          maximum: 5
        comments:
          type: string
        providedBy:
          type: string
        providedAt:
          type: string
          format: date-time
  responses:
    BadRequest:
      description: Invalid JSON body or failed field validation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
    Conflict:
      description: >-
        Conflict with the current state of the object (already resolved, already
        exists, or modified concurrently — retry)
      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'
    InternalError:
      description: Kubernetes API call failed
      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).

````