decide-fyi Benchmarks API

openapi: 3.2.0
info:
  title: Decide Decision Benchmarks 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: Benchmarks
  description: Opt-in anonymized cross-customer benchmarks with minimum privacy thresholds.
paths:
  /api/decision/policies/{policy_id}/benchmarks:
    get:
      tags:
      - Benchmarks
      operationId: getPolicyBenchmarks
      summary: Read anonymized policy benchmarks
      description: Returns decision_benchmark_v1 with caller metrics and opt-in anonymized cohort percentiles when minimum cohort privacy thresholds are met. Raw customer records are never exposed.
      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: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 250000
          default: 5000
      - name: min_cohort_scopes
        in: query
        required: false
        schema:
          type: integer
          minimum: 2
          maximum: 10000
          default: 3
      - name: min_cohort_decisions
        in: query
        required: false
        schema:
          type: integer
          minimum: 5
          maximum: 1000000
          default: 30
      responses:
        '200':
          description: Anonymized policy benchmark report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionBenchmark'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    DecisionBenchmark:
      type: object
      required:
      - ok
      - decision_benchmark_version
      - policy_id
      - privacy
      - your_metrics
      - cross_customer
      - recommendation
      - benchmark_hash
      properties:
        ok:
          type: boolean
        decision_benchmark_version:
          type: string
          const: decision_benchmark_v1
        generated_at:
          type: string
        source:
          type: string
          const: decision_outcomes
        scope:
          type: string
          const: caller_api_key_plus_anonymized_opt_in_cohort
        policy_id:
          type: string
        policy_version:
          type:
          - string
          - 'null'
        privacy:
          type: object
          properties:
            anonymized:
              type: boolean
            raw_records_exposed:
              type: boolean
              const: false
            caller_excluded_from_cohort:
              type: boolean
            opt_in_required:
              type: boolean
            enabled:
              type: boolean
            minimum_cohort_scopes:
              type: integer
            minimum_cohort_decisions:
              type: integer
          additionalProperties: true
        your_metrics:
          type: object
          additionalProperties: true
        cross_customer:
          type: object
          properties:
            status:
              type: string
              enum:
              - available
              - insufficient_cohort
              - no_cohort_data
              - disabled
            cohort_scopes:
              type: integer
            cohort_decisions:
              type: integer
            threshold_met:
              type: boolean
            metrics:
              type:
              - object
              - 'null'
              additionalProperties: true
            percentiles:
              type:
              - object
              - 'null'
              additionalProperties: true
          additionalProperties: true
        comparison:
          type:
          - object
          - 'null'
          additionalProperties: true
        recommendation:
          type: string
          enum:
          - benchmark_unavailable
          - within_cohort_range
          - review_policy_outcomes
          - tighten_approval_policy
          - reduce_manual_review_pressure
        benchmark_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