API Evangelist enhancements for the Blnk Core OpenAPI

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Blnk Core OpenAPI
  version: 1.0.0
x-provenance:
  generated: '2026-08-27'
  method: generated
  source: openapi/blnkfinance-core-openapi.json
  extends: openapi/blnkfinance-core-openapi.json
  upstream: https://docs.blnkfinance.com/openapi.json
  note: >-
    Non-destructive. Everything below is sourced from Blnk's own published documentation, not invented:
    the auth scheme from /advanced/configuration/server-security, the error envelope and codes from
    /advanced/error-codes, the reversal semantics from /transactions/refunds and
    /transactions/inflight/updating-inflight. The original spec is never mutated. The apis.io scorer
    parses the ORIGINAL, so this overlay improves derived artifacts and client generation, not the raw
    contract-content score.
  gaps_addressed:
  - The spec declares only http/basic and applies security to zero operations, while every documented call uses the X-Blnk-Key header.
  - The spec declares no 4xx/5xx responses across all 18 operations.
  - Every operation is untagged; the only declared tag is "Misc".
  - info has no description, license, or termsOfService.
actions:
- target: $.info
  update:
    description: >-
      Blnk Core is an open-source double-entry ledger for financial products -- wallets, loans, payouts,
      escrow and cards. This contract covers the self-hosted Core REST surface: ledgers, balances,
      transactions (including inflight holds and refunds), identities, accounts, balance monitors and
      backup. Transactions are append-only; reversals are recorded as new child transactions linked by
      parent_transaction.
    license:
      name: Apache-2.0
      url: https://blnkfinance.com/legal/open-source-license
    termsOfService: https://blnkfinance.com/legal/terms
    contact:
      name: Blnk Finance Support
      email: support@blnkfinance.com
      url: https://docs.blnkfinance.com
- target: $.info
  update:
    x-api-evangelist:
      docs: https://docs.blnkfinance.com/reference/overview
      error_catalog: errors/blnkfinance-error-codes.yml
      conventions: conventions/blnkfinance-conventions.yml
      scopes: scopes/blnkfinance-scopes.yml
- target: $.components.securitySchemes
  update:
    blnkKey:
      type: apiKey
      in: header
      name: X-Blnk-Key
      description: >-
        Master key (BLNK_SERVER_SECRET_KEY) or a scoped API key. Only enforced when
        BLNK_SERVER_SECURE=true; the shipped default is false, which skips authentication entirely.
        Scoped keys carry resource:action permissions -- see scopes/blnkfinance-scopes.yml.
- target: $.servers
  update:
  - url: http://localhost:5001
    description: >-
      Docker Compose default for a locally running Blnk Core. Blnk Core is self-hosted open source and
      has no vendor-operated public host; in production this is the operator's own instance URL, which
      Blnk's docs write as http://YOUR_BLNK_INSTANCE_URL.
- target: $.tags
  update:
  - name: Ledgers
    description: Create and read ledgers, the container for balances.
  - name: Balances
    description: Create and read balances, and manage balance monitors.
  - name: Transactions
    description: Record money movements, update inflight holds, and issue refunds.
  - name: Identities
    description: Create, read and update the people and organizations balances belong to.
  - name: Accounts
    description: Bank-account representations bound to a balance and an identity.
  - name: Admin
    description: Database backup operations.
- target: $.paths['/ledgers'].post
  update:
    tags: [Ledgers]
    security:
    - blnkKey: []
    x-required-scope: 'ledgers:write'
- target: $.paths['/ledgers/{ledger_id}'].get
  update:
    tags: [Ledgers]
    security:
    - blnkKey: []
    x-required-scope: 'ledgers:read'
- target: $.paths['/balances'].post
  update:
    tags: [Balances]
    security:
    - blnkKey: []
    x-required-scope: 'balances:write'
- target: $.paths['/balances/{id}'].get
  update:
    tags: [Balances]
    security:
    - blnkKey: []
    x-required-scope: 'balances:read'
- target: $.paths['/balance-monitors'].post
  update:
    tags: [Balances]
    security:
    - blnkKey: []
    x-required-scope: 'balance-monitors:write'
- target: $.paths['/balance-monitors/{id}'].get
  update:
    tags: [Balances]
    security:
    - blnkKey: []
    x-required-scope: 'balance-monitors:read'
- target: $.paths['/balance-monitors/{id}'].put
  update:
    tags: [Balances]
    security:
    - blnkKey: []
    x-required-scope: 'balance-monitors:write'
- target: $.paths['/transactions'].post
  update:
    tags: [Transactions]
    security:
    - blnkKey: []
    x-required-scope: 'transactions:write'
    x-idempotency:
      field: reference
      behavior: reject
      duplicate_status: 409
      duplicate_code: TXN_DUPLICATE_REFERENCE
      note: Caller-supplied reference is unique at the database layer since Core 0.13.2. A duplicate is rejected, not replayed.
    x-dry-run:
      field: dry_run
      since: 0.15.3
    x-reversibility:
      reversal: RefundTransaction
      note: An APPLIED transaction can be refunded exactly once. An INFLIGHT hold is committed, voided, or auto-voided at inflight_expiry_date.
    x-async:
      default: queued
      opt_out_field: skip_queue
      note: 'Defaults to skip_queue false; the create call returns status QUEUED and the applied record arrives later with a _q reference suffix.'
- target: $.paths['/transactions/inflight/{txID}'].put
  update:
    tags: [Transactions]
    security:
    - blnkKey: []
    x-required-scope: 'transactions:write'
    x-reversibility:
      action: void
      window: until commit, or until inflight_expiry_date passes (auto-void)
- target: $.paths['/refund-transaction/{id}'].post
  update:
    tags: [Transactions]
    security:
    - blnkKey: []
    x-required-scope: 'transactions:write'
    x-reversibility:
      action: refund
      once_only: true
      note: Each original transaction can be refunded only once; a second attempt is rejected. The original record is never modified.
- target: $.paths['/identities'].post
  update:
    tags: [Identities]
    security:
    - blnkKey: []
    x-required-scope: 'identities:write'
    x-pii: true
- target: $.paths['/identities/{id}'].get
  update:
    tags: [Identities]
    security:
    - blnkKey: []
    x-required-scope: 'identities:read'
    x-pii: true
- target: $.paths['/identities/{id}'].put
  update:
    tags: [Identities]
    security:
    - blnkKey: []
    x-required-scope: 'identities:write'
    x-pii: true
- target: $.paths['/accounts'].post
  update:
    tags: [Accounts]
    security:
    - blnkKey: []
    x-required-scope: 'accounts:write'
- target: $.paths['/accounts/{id}'].get
  update:
    tags: [Accounts]
    security:
    - blnkKey: []
    x-required-scope: 'accounts:read'
- target: $.paths['/accounts/{id}'].put
  update:
    tags: [Accounts]
    security:
    - blnkKey: []
    x-required-scope: 'accounts:write'
- target: $.paths['/backup'].post
  update:
    tags: [Admin]
    security:
    - blnkKey: []
    x-required-scope: 'backup:write'
- target: $.paths['/backup/s3'].post
  update:
    tags: [Admin]
    security:
    - blnkKey: []
    x-required-scope: 'backup:write'
- target: $.components.schemas
  update:
    BlnkError:
      type: object
      description: >-
        Blnk's error envelope (Core 0.15.0+). Branch on error_detail.code, never on message text. Full
        catalog of 72 codes in errors/blnkfinance-error-codes.yml.
      properties:
        error:
          type: string
          description: Display text, retained for backwards compatibility.
        error_detail:
          type: object
          properties:
            code:
              type: string
              description: Stable, domain-prefixed error code (GEN_, AUTH_, TXN_, BAL_, LGR_, IDT_, RECON_, META_, HOOK_, QUEUE_, SRCH_, ADMIN_, APIKEY_).
              example: TXN_DUPLICATE_REFERENCE
            message:
              type: string
              description: Human-readable. May change between releases.
            details:
              type: object
              description: Optional structured context.