Dibri API - API Evangelist enhancements

overlay: 1.0.0
info:
  title: Dibri API - API Evangelist enhancements
  version: '2026-11-05'
  x-provenance:
    method: derived
    generated: '2026-11-05'
    source: https://dibri.ai/developers
extends: ../openapi/_ae-authored/dibri-ai-openapi-generated.yml
actions:
- target: $.components.schemas.PostApiV1AgentQueryRequest
  description: Request fields as documented on https://dibri.ai/developers.
  update:
    required: [message]
    properties:
      message:
        type: string
        maxLength: 4000
        description: The question, up to 4,000 characters.
      conversation_history:
        type: array
        description: Earlier turns, oldest first. The last 6 turns are used.
        items:
          type: object
          required: [role, content]
          properties:
            role: {type: string, enum: [user, assistant]}
            content: {type: string}
- target: $.components.schemas
  description: Response and error schemas as documented.
  update:
    AgentQueryResponse:
      type: object
      required: [answer, sources, confidence_score, blocked]
      properties:
        answer: {type: string, description: "Markdown answer built only from the vault's approved documents; [n] references point to sources."}
        sources:
          type: array
          items:
            type: object
            properties:
              filename: {type: string}
              content: {type: string, description: "First 300 characters."}
              passages:
                type: array
                items:
                  type: object
                  properties:
                    text: {type: string}
                    distance: {type: [number, 'null']}
              distance: {type: [number, 'null'], description: "Lower means a closer match."}
              source_url: {type: [string, 'null']}
        confidence_score: {type: integer, minimum: 0, maximum: 100, description: "0 when blocked."}
        blocked: {type: boolean, description: "True when nothing verified covers the question."}
        blocked_reason: {type: [string, 'null']}
    Error:
      type: object
      properties:
        detail: {type: string}
- target: $.paths['/api/v1/agent/query'].post
  description: Document the response body, errors and the MCP equivalent.
  update:
    description: Send one question, get one answer built only from the agent's vault, with sources and a confidence score, or a refusal (blocked=true). Each call counts as one answer, refusals included.
    x-mcp-tool: {server: 'https://dibri.ai/mcp', tool: ask}
    responses:
      '401':
        description: The agent token is missing, invalid or expired.
        content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}
      '402':
        description: Subscription inactive or monthly answer limit reached; detail says which. Treat like a refusal and hand off to a person.
        content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}
      '502':
        description: The upstream model returned an error. Retry the request.
        content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}
- target: $.paths['/api/v1/agent/query'].post.responses['201']
  description: Attach the documented response body to the success response.
  update:
    content: {application/json: {schema: {$ref: '#/components/schemas/AgentQueryResponse'}}}
- target: $.paths['/api/v1/analytics'].get
  update:
    description: Read-only list of every trust tool and its parameters. Uses an analytics key (dbk_), not an agent token; not counted as answers.
- target: $.paths['/api/v1/analytics/knowledge_gaps'].get
  update:
    description: Topics no approved document covers, with sample questions. Analytics key (dbk_). Parameters days, limit, vault_id.
    x-mcp-tool: {server: 'https://dibri.ai/mcp', tool: knowledge_gaps}