Deliverd Risk Indicators API

openapi: 3.2.0
info:
  title: Deliverd Dev Risk Indicators API
  version: 1.0.0
  x-refined-note:
  - x-source differs across the merged source definitions and was not carried
  description: 'Operations tagged Risk Indicators across 2 of this provider''s published API definitions: deliverd-dev-openapi.json, deliverd-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://deliverd.dev
  description: 'Deliverd REST API (paths carry the /api/v1 prefix; https://deliverd.dev/llms.txt: "REST API: https://deliverd.dev/api/v1")'
tags:
- name: Risk Indicators
paths:
  /api/v1/risk-indicators:
    get:
      summary: The AI risk scorecard for a whole month
      description: 'Each indicator the appetite turns on: its figure for the month against the limits it was judged by (`green`, `amber`, `red` or `not_measurable`), the two months before, the trend, where a measured indicator stands this month so far, whether a submitted figure is still owed, and the corrective action the month opened. Lower is better for every indicator. Deliverd never stops an agent on a figure.'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          pattern: ^\d{4}-(0[1-9]|1[0-2])$
        required: false
        name: period
        in: query
      responses:
        '200':
          description: '{ access, period, periodLabel, appetite, baseline, summary, indicators }'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
        '402':
          description: The plan does not include the AI risk scorecard (feature_unavailable)
      tags:
      - Risk Indicators
      operationId: getApiV1RiskIndicators
      x-operation-id-source: derived
  /api/v1/risk-indicators/{key}/readings:
    post:
      summary: Give a submitted indicator's figure for a month
      description: 'For an indicator whose figure comes from outside Deliverd: access reviews, output sampling, downtime, training. Give `value`, or `numerator` and `denominator` for a ratio, and `evidence` saying where it comes from. Judged against the limits in force when it is saved. A key gives a month''s first figure; correcting one is a person''s, in the app, with a reason. 409 when a figure already stands.'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
        required: true
        name: key
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                period:
                  type: string
                  pattern: ^\d{4}-(0[1-9]|1[0-2])$
                  description: The whole month the figure is for, YYYY-MM
                value:
                  type: number
                  minimum: 0
                  description: 'The figure: a count, minutes, or a percentage. Omit for a ratio indicator and give numerator and denominator'
                numerator:
                  type: integer
                  minimum: 0
                  description: 'For a ratio indicator: how many were in the condition counted'
                denominator:
                  type: integer
                  minimum: 0
                  description: 'For a ratio indicator: how many there were in all'
                completeness:
                  type: number
                  minimum: 0
                  maximum: 100
                  description: How much of what should have been counted was counted, as a percentage
                evidence:
                  type: string
                  minLength: 1
                  maxLength: 4000
                  description: 'Where the figure comes from: the report, review or system, and where to find it'
                note:
                  type: string
                  maxLength: 2000
              required:
              - period
              - evidence
      responses:
        '201':
          description: The reading
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
        '402':
          description: The plan does not include Compliance Mode (feature_unavailable). Reads are not refused.
      tags:
      - Risk Indicators
      operationId: postApiV1RiskIndicatorsByKeyReadings
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key (dlv_…) created in Settings → API tokens, or an OAuth access token (dlvo_…). Every route below can answer `401 auth_error` — the credential was not accepted — or `403 insufficient_scope`, which is a different thing: the credential is fine and was not issued with the scope this route needs. Reissue it with that scope rather than replacing it with another of the same ones. Older clients may still branch on `auth_error` for both.'
x-refined-from:
- deliverd-dev-openapi.json
- deliverd-dev-openapi.yml