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

# Lacunas de conhecimento

> O que os clientes perguntam e a memória não tem, qual fonte poderia gravar, as perguntas que ela responde sempre e as respostas prontas propostas; contagens, nunca um cliente.



## OpenAPI

````yaml openapi/pt/cell.json GET /v1/insights/gaps
openapi: 3.1.0
info:
  title: API de dados da Niadra
  version: '1'
  description: >-
    Escrita, contexto, histórico, objetos, identidade, privacidade e governança
    de um espaço. Cada espaço tem um endereço estável, com o espaço e a região
    no nome.
servers:
  - url: https://{space}.{region}.api.niadra.com
    variables:
      space:
        default: acme-prod
        description: O espaço, que vem na chave de fonte.
      region:
        default: us-east-2
        description: A região do espaço, que também vem na chave.
security: []
paths:
  /v1/insights/gaps:
    get:
      summary: Lacunas de conhecimento
      description: >-
        O que os clientes perguntaram e a memória não tinha registro, o que os
        agentes tiveram de perguntar a eles, qual fonte poderia gravar, as
        perguntas que a memória responde sempre e as respostas prontas
        propostas. Contagens por assunto e categoria numa janela de `days` dias,
        cada cliente contado uma vez; grupos abaixo do tamanho mínimo e
        categorias que a política do analista nega ficam de fora. Pessoas com o
        papel de análise ou admin, ou chaves com o escopo `analytics`; deixa um
        comprovante de análise.


        **Autenticação.** Chave de fonte com o escopo `analytics`, ou token de
        pessoa do Console com o papel analysis (ou admin). Pessoas do papel
        vendor não acessam.
      operationId: knowledge_gaps_v1_insights_gaps_get
      parameters:
        - in: query
          name: days
          required: false
          schema:
            default: 30
            maximum: 90
            minimum: 1
            title: Days
            type: integer
          description: >-
            A janela, em dias; as contagens contam cada cliente uma vez dentro
            dela.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GapsResponse'
          description: >-
            As lacunas, as perguntas recorrentes e as propostas da janela, com
            os grupos retidos.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: O pedido não bate com o contrato.
      security:
        - sourceKey: []
components:
  schemas:
    GapsResponse:
      additionalProperties: false
      description: >-
        O que os clientes perguntam e a memória não consegue responder, e o que
        ela responde sempre. Contagens por assunto e categoria, nunca um
        cliente, um valor ou um texto.
      properties:
        gaps:
          items:
            $ref: '#/components/schemas/GapOut'
          title: Gaps
          type: array
          description: >-
            O que os clientes pediram e a memória não tinha registro, ou os
            agentes tiveram de perguntar a clientes que voltaram.
        proposals:
          items:
            $ref: '#/components/schemas/ProposalOut'
          title: Proposals
          type: array
          description: >-
            Respostas prontas propostas por regra; nada chega aos agentes até o
            time aprovar a configuração.
        recurring:
          items:
            $ref: '#/components/schemas/RecurringOut'
          title: Recurring
          type: array
          description: As perguntas que a memória responde sempre, por assunto e categoria.
        since:
          format: date
          title: Since
          type: string
          description: Início da janela.
        until:
          format: date
          title: Until
          type: string
          description: Fim da janela.
        withheld_groups:
          description: >-
            Grupos deixados de fora: menos clientes do que o tamanho mínimo de
            grupo, ou uma categoria que a política do analista nega.
          title: Withheld Groups
          type: integer
      required:
        - since
        - until
        - gaps
        - recurring
        - proposals
        - withheld_groups
      title: GapsResponse
      type: object
    Problem:
      additionalProperties: false
      description: >-
        Detalhes do problema no formato da RFC 9457; `code` vem do catálogo de
        erros versionado.
      properties:
        code:
          title: Code
          type: string
        detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Detail
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Request Id
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          default: about:blank
          title: Type
          type: string
      required:
        - title
        - status
        - code
      title: Problem
      type: object
    GapOut:
      additionalProperties: false
      properties:
        answered_share:
          anyOf:
            - type: number
            - type: 'null'
          description: >-
            Para um tipo de valor, a fração dos turnos que o pediram e a memória
            respondeu.
          title: Answered Share
        could_record:
          description: >-
            Fontes que poderiam enviá-lo; vazio quando nenhuma envia, o que é
            uma lacuna estrutural.
          items:
            $ref: '#/components/schemas/GapSource'
          title: Could Record
          type: array
        customers:
          description: Clientes distintos na janela, estimados com cerca de 3% de erro.
          title: Customers
          type: integer
        key:
          description: '`<tipo>:<assunto>:<categoria>`; a chave de uma decisão.'
          title: Key
          type: string
        kind:
          description: >-
            `no_record`: clientes pediram um tipo de valor e a memória não tinha
            registro; `agent_question`: agentes tiveram de perguntar a clientes
            que voltaram um predicado do qual a memória não tinha linha.
          enum:
            - no_record
            - agent_question
          title: Kind
          type: string
        review:
          anyOf:
            - $ref: '#/components/schemas/GapReviewOut'
            - type: 'null'
        subject:
          description: Um tipo de valor (`invoice`, `protocol`...) ou um predicado.
          title: Subject
          type: string
        topic:
          description: >-
            A categoria normalizada da conversa; vazio quando nenhuma foi
            medida.
          title: Topic
          type: string
        turns:
          title: Turns
          type: integer
      required:
        - key
        - kind
        - subject
        - topic
        - customers
        - turns
        - could_record
      title: GapOut
      type: object
    ProposalOut:
      additionalProperties: false
      properties:
        key:
          description: '`<tipo>:<assunto>:<categoria>`; a chave de uma decisão.'
          title: Key
          type: string
        kind:
          description: >-
            `not_recorded`: nenhuma fonte grava o assunto, então a ausência dele
            nunca deve ser lida como do cliente; `settled`: as regras respondem
            a pergunta quase sempre.
          enum:
            - not_recorded
            - settled
          title: Kind
          type: string
        review:
          anyOf:
            - $ref: '#/components/schemas/GapReviewOut'
            - type: 'null'
          description: A decisão do time sobre ela, quando há uma.
        subject:
          title: Subject
          type: string
          description: Um tipo de valor ou um predicado.
        text:
          description: A linha pronta proposta, no idioma do espaço.
          title: Text
          type: string
        topic:
          title: Topic
          type: string
          description: A categoria normalizada; vazio quando nenhuma.
      required:
        - key
        - kind
        - subject
        - topic
        - text
      title: ProposalOut
      type: object
      description: Uma linha pronta proposta por regra para o espaço.
    RecurringOut:
      additionalProperties: false
      properties:
        answered_share:
          description: A fração dos turnos que a pediram e a memória respondeu.
          title: Answered Share
          type: number
        customers:
          description: Clientes distintos na janela, estimados com cerca de 3% de erro.
          title: Customers
          type: integer
        key:
          description: '`<tipo>:<assunto>:<categoria>`; a chave de uma decisão.'
          title: Key
          type: string
        review:
          anyOf:
            - $ref: '#/components/schemas/GapReviewOut'
            - type: 'null'
          description: A decisão do time sobre ela, quando há uma.
        subject:
          title: Subject
          type: string
          description: Um tipo de valor ou um predicado.
        topic:
          title: Topic
          type: string
          description: >-
            A categoria normalizada das conversas; vazio quando nenhuma foi
            medida.
        turns:
          title: Turns
          type: integer
          description: Turnos que a pediram na janela.
      required:
        - key
        - subject
        - topic
        - customers
        - turns
        - answered_share
      title: RecurringOut
      type: object
      description: Uma pergunta que os clientes fazem sempre e a memória responde.
    GapSource:
      additionalProperties: false
      properties:
        name:
          title: Name
          type: string
          description: A fonte como o Console a nomeia.
        source_id:
          title: Source Id
          type: string
          description: A fonte.
        via:
          description: >-
            `mapping`: o mapeamento do webhook da fonte traz o tipo; `schema`: a
            extração capta o predicado quando uma conversa o afirma.
          enum:
            - mapping
            - schema
          title: Via
          type: string
      required:
        - source_id
        - name
        - via
      title: GapSource
      type: object
      description: Uma fonte do espaço que poderia gravar o assunto que falta.
    GapReviewOut:
      additionalProperties: false
      properties:
        decided_at:
          format: date-time
          title: Decided At
          type: string
          description: Quando foi gravada.
        decided_by:
          title: Decided By
          type: string
          description: 'Quem gravou: a pessoa, ou a chave.'
        decision:
          enum:
            - accepted
            - dismissed
          title: Decision
          type: string
          description: '`accepted` ou `dismissed`.'
        note:
          anyOf:
            - type: string
            - type: 'null'
          title: Note
          description: A nota deixada com ela.
      required:
        - decision
        - decided_by
        - decided_at
      title: GapReviewOut
      type: object
      description: Uma decisão como foi gravada.
  securitySchemes:
    sourceKey:
      type: http
      scheme: bearer
      description: nia_sk_...

````