JNexum Ask API

openapi: 3.2.0
info:
  title: JNexum Ask API
  version: 0.2.0
tags:
- name: Ask
paths:
  /ask:
    post:
      summary: Ask
      operationId: ask_ask_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Ask
  /ask/stream:
    post:
      summary: Ask Stream
      description: 'Mesma resposta de /ask, entregue por SSE conforme o modelo escreve.


        Existe porque o spinner opaco de 11-32s era O achado da auditoria de

        26/09/2026: aqui o primeiro quadro sai imediatamente e o texto começa a

        aparecer no tempo de retrieval+rerank, não no tempo total. /ask continua

        intacto e é o fallback do cliente (além de ser o contrato da API/MCP).


        Protocolo (um quadro por evento):

        etapa {"fase":"busca"|"rerank"|"geracao", ...} progresso

        na fase "busca" de um follow-up reusado vem também

        {"reuso":true,"texto":"Usando os precedentes já encontrados…"}

        delta {"t":"…"} pedaço novo de texto

        fontes {"fontes":[…],"pesquisa_token":"…",

        "contexto_ids":[…],"origem_pool":"reuso"|"nova"} uma vez, após o texto

        fim {"total_ms":N} último quadro

        erro {"status":N,"detail":"…"} falha depois do 1º byte

        Mais o comentário `: ping` durante as esperas longas.


        Os gates (401/402/403/429) rodam ANTES de qualquer byte e continuam saindo

        como status HTTP normal. `citacoes_reprovadas` continua só no log, nunca no

        corpo — mesma política de /ask.'
      operationId: ask_stream_ask_stream_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Ask
components:
  schemas:
    AskRequest:
      properties:
        query:
          type: string
          maxLength: 500
          minLength: 3
          title: Query
        top_k:
          type: integer
          maximum: 15.0
          minimum: 1.0
          title: Top K
          default: 6
        tribunal:
          anyOf:
          - type: string
          - type: 'null'
          title: Tribunal
        tipo:
          anyOf:
          - type: string
          - type: 'null'
          title: Tipo
        area:
          anyOf:
          - type: string
          - type: 'null'
          title: Area
        relator:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Relator
        data_inicio:
          anyOf:
          - type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          - type: 'null'
          title: Data Inicio
        data_fim:
          anyOf:
          - type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          - type: 'null'
          title: Data Fim
        turnos:
          items:
            $ref: '#/components/schemas/Turno'
          type: array
          maxItems: 20
          title: Turnos
        contexto_ids:
          items:
            type: integer
            exclusiveMinimum: 0.0
          type: array
          maxItems: 15
          title: Contexto Ids
        forcar_busca:
          type: boolean
          title: Forcar Busca
          default: false
      type: object
      required:
      - query
      title: AskRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Turno:
      properties:
        papel:
          type: string
          enum:
          - usuario
          - assistente
          title: Papel
        texto:
          type: string
          maxLength: 2000
          minLength: 1
          title: Texto
      additionalProperties: false
      type: object
      required:
      - papel
      - texto
      title: Turno
      description: 'Um turno da conversa, enviado pelo cliente a cada follow-up.


        Sem estado no servidor (conversa com follow-up, 26/09/2026): o histórico vive

        no sessionStorage do navegador e volta inteiro em cada request. Validação

        estrita — `extra="forbid"` para um campo escrito errado virar 422 em vez de

        ser silenciosamente ignorado.'