decide-fyi Confidence API

openapi: 3.2.0
info:
  title: Decide Decision Confidence API
  summary: Decision protocol for state-changing software actions.
  description: Call Decide before products, agents, queues, billing systems, CRMs, or internal tools change state. The API returns a signed Decision Record v1 object with policy bundle attestation, evidence, action binding, replay, verification handles, portable Decision Packet v1 exports, simulation-only counterfactual analysis, cryptographic audit chains, Action Execution Receipts, Outcome Records, CRM Sync Records, predictive confidence, first-party policy pattern templates, policy effectiveness metrics, opt-in anonymized benchmarks, and explainable anomaly reports derived from reported outcomes.
  version: 1.13.0
  x-decision-protocol-version: decision_protocol_v1
  x-decision-record-version: decision_record_v1
  x-decision-packet-version: decision_packet_v1
servers:
- url: https://www.decide.fyi
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Confidence
  description: Predictive decision confidence from caller-scoped Outcome Records.
paths:
  /api/decision/policies/{policy_id}/confidence:
    get:
      tags:
      - Confidence
      operationId: getPolicyConfidence
      summary: Read predictive policy confidence
      description: Returns decision_confidence_v1 for a candidate verdict/action using latest Decision Outcome records within the caller API-key scope. Scores are deterministic confidence signals, not causal ML claims.
      parameters:
      - name: policy_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 180
      - name: policy_version
        in: query
        required: false
        schema:
          type: string
          maxLength: 180
      - name: verdict
        in: query
        required: false
        schema:
          type: string
          default: 'yes'
      - name: action
        in: query
        required: false
        schema:
          type: string
          maxLength: 140
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100000
          default: 1000
      - name: min_sample
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100000
          default: 10
      responses:
        '200':
          description: Decision confidence baseline
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionConfidence'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    DecisionConfidence:
      type: object
      required:
      - ok
      - decision_confidence_version
      - score
      - level
      - recommendation
      - confidence_hash
      properties:
        ok:
          type: boolean
        decision_confidence_version:
          type: string
          const: decision_confidence_v1
        generated_at:
          type: string
        source:
          type: string
          const: decision_outcomes
        scope:
          type: string
          const: caller_api_key
        decision_id:
          type:
          - string
          - 'null'
        policy_id:
          type:
          - string
          - 'null'
        policy_version:
          type:
          - string
          - 'null'
        verdict:
          type: string
        action:
          type:
          - string
          - 'null'
        score:
          type: number
          minimum: 0
          maximum: 1
        level:
          type: string
          enum:
          - high
          - medium
          - low
          - weak
          - insufficient_data
        based_on:
          type: integer
        similar_decisions:
          type: integer
        policy_stability:
          type: string
          enum:
          - high
          - medium
          - low
          - insufficient_data
        recommendation:
          type: string
          enum:
          - collect_more_outcomes
          - high_confidence_proceed
          - high_confidence_block
          - high_confidence_review
          - proceed_with_monitoring
          - route_for_review
          - monitor
        metrics:
          type: object
          additionalProperties: true
        baseline:
          type: object
          additionalProperties: true
        data_quality:
          type: object
          additionalProperties: true
        reasons:
          type: array
          items:
            type: object
            additionalProperties: true
        confidence_hash:
          type: string
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        c:
          type: string
        v:
          type: string
        request_id:
          type: string
        error:
          type: string
        message:
          type: string
      additionalProperties: true
  responses:
    Unauthorized:
      description: API key missing, invalid, inactive, or unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key