Backwork Certified Releases API

openapi: 3.2.0
info:
  title: Backworkhealth Com Certified Releases API
  version: 1.0.0
  contact:
    email: support@backworkhealth.com
    url: https://backworkhealth.com
  license:
    name: Proprietary
    url: https://backworkhealth.com/terms
  description: 'Operations tagged Certified Releases across 2 of this provider''s published API definitions: backworkhealth-com-openapi.json, backworkhealth-com-v1-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://backworkhealth.com/api/v1
  description: Production server
- url: http://localhost:3000/api/v1
  description: Local development
security:
- bearerAuth: []
tags:
- name: Certified Releases
  description: Entitlement-gated, immutable commercial release snapshots with evidence-bound metadata
paths:
  /releases/{releaseId}/decisions:
    get:
      tags:
      - Certified Releases
      summary: List decisions from a certified release
      description: 'Returns only the immutable `derived_decision_v1` allowlist from one `certified_release.v1` snapshot. This surface requires a dedicated API key whose complete scope set is exactly `certified:derived_decision:read`; OAuth credentials, ordinary `read` or `admin` keys, and keys carrying any additional scope are not valid for this endpoint. The key must also hold an active entitlement to the requested release. Responses are JSON only: omit `format` and `_format`, and omit `Accept` or request `application/json` (a wildcard Accept header is also treated as JSON). CSV or FHIR negotiation returns 406. Missing, expired, revoked, schema-incompatible, and unentitled releases intentionally share the same non-enumerating 404 response, sent with `Cache-Control: private, no-store`. An authorized query with no matching decision returns 200 with an empty data array.'
      operationId: listCertifiedReleaseDecisions
      x-backwork-required-scopes:
      - certified:derived_decision:read
      x-backwork-scope-match: exact
      x-backwork-response-formats:
      - application/json
      parameters:
      - name: releaseId
        in: path
        description: Content-addressed certified release ID assigned to the dedicated key
        required: true
        schema:
          type: string
          pattern: ^bwr_[0-9a-f]{64}$
      - name: code
        in: query
        description: CPT, HCPCS, ICD-10-CM, or ICD-10-PCS code. Input is normalized to uppercase.
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 20
          pattern: ^[A-Za-z0-9.]+$
      - name: code_system
        in: query
        description: Optional code-system filter
        required: false
        schema:
          type: string
          enum:
          - CPT
          - HCPCS
          - ICD10CM
          - ICD10PCS
      - name: payer_code
        in: query
        description: Optional canonical payer-code filter. Input is normalized to uppercase.
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 100
          pattern: ^[A-Za-z0-9_.-]+$
      - name: cursor
        in: query
        description: Decision ID returned as the prior page's pagination cursor
        required: false
        schema:
          type: string
          pattern: ^bwd_[0-9a-f]{64}$
      - name: limit
        in: query
        description: Results per page
        required: false
        schema:
          default: 50
          type: integer
          minimum: 1
          maximum: 100
      - name: Accept
        in: header
        description: Omit this header or request `application/json`. `*/*` also resolves to JSON. Requests negotiating `text/csv` or `application/fhir+json` receive 406.
        required: false
        schema:
          default: application/json
          type: string
      responses:
        '200':
          description: Decisions from the certified release
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CertifiedDecision'
                  meta:
                    $ref: '#/components/schemas/CertifiedDecisionResponseMeta'
                required:
                - success
                - data
                - meta
        '400':
          description: 'Error: `VALIDATION_ERROR`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: Request validation failed
                  hint: Fix the fields listed in details, then send the corrected request
                  docUrl: https://backworkhealth.com/docs/errors#validation-error
                  retryable: false
                meta:
                  request_id: req_abc123
                  timestamp: '2024-01-15T10:30:00Z'
        '401':
          description: 'Error: `AUTH_MISSING`, `AUTH_INVALID_FORMAT`, `AUTH_INVALID_TOKEN`, `AUTH_KEY_NOT_FOUND`, `AUTH_KEY_REVOKED`, `AUTH_KEY_SUSPENDED`, `AUTH_TEST_KEY_SANDBOX_ONLY`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: AUTH_MISSING
                  message: Missing Authorization header
                  hint: 'Include "Authorization: Bearer bwk_xxx" header'
                  docUrl: https://backworkhealth.com/docs/errors#auth-missing
                  retryable: false
                meta:
                  request_id: req_abc123
                  timestamp: '2024-01-15T10:30:00Z'
        '402':
          description: 'Error: `BILLING_CREDITS_EXHAUSTED`, plan-gate denial'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ErrorResponse'
                - $ref: '#/components/schemas/GateDenialResponse'
              example:
                success: false
                error:
                  code: BILLING_CREDITS_EXHAUSTED
                  message: Your organization has no request credits left for this call
                  hint: details.requests_required is this call's cost and details.requests_available is the balance. Retry once the balance covers the call. An organization admin can manage the plan and usage in the Backwork dashboard at https://backworkhealth.com/api-usage
                  docUrl: https://backworkhealth.com/docs/errors#billing-credits-exhausted
                  retryable: false
                meta:
                  request_id: req_abc123
                  timestamp: '2024-01-15T10:30:00Z'
        '403':
          description: 'Error: `AUTHZ_SCOPE_REQUIRED`, `AUTHZ_ORIGIN_NOT_ALLOWED`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: AUTHZ_SCOPE_REQUIRED
                  message: Insufficient permissions for this operation
                  hint: details.required_scopes lists the scopes this operation accepts
                  docUrl: https://backworkhealth.com/docs/errors#authz-scope-required
                  retryable: false
                meta:
                  request_id: req_abc123
                  timestamp: '2024-01-15T10:30:00Z'
        '404':
          description: 'Error: `RESOURCE_RELEASE_NOT_AVAILABLE`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: RESOURCE_RELEASE_NOT_AVAILABLE
                  message: Certified release is not available
                  hint: Use the release ID assigned to this dedicated certified-data key
                  docUrl: https://backworkhealth.com/docs/errors#resource-release-not-available
                  retryable: false
                meta:
                  request_id: req_abc123
                  timestamp: '2024-01-15T10:30:00Z'
        '406':
          description: 'Error: `REQUEST_FORMAT_NOT_ACCEPTABLE`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: REQUEST_FORMAT_NOT_ACCEPTABLE
                  message: Requested response format is not available
                  hint: Certified release endpoints support JSON only
                  docUrl: https://backworkhealth.com/docs/errors#request-format-not-acceptable
                  retryable: false
                meta:
                  request_id: req_abc123
                  timestamp: '2024-01-15T10:30:00Z'
        '429':
          description: 'Error: `RATE_LIMIT_EXCEEDED`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: RATE_LIMIT_EXCEEDED
                  message: Rate limit exceeded
                  hint: Wait the number of seconds in the Retry-After header, then retry
                  docUrl: https://backworkhealth.com/docs/errors#rate-limit-exceeded
                  retryable: true
                meta:
                  request_id: req_abc123
                  timestamp: '2024-01-15T10:30:00Z'
        '500':
          description: 'Error: `SERVER_INTERNAL_ERROR`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: SERVER_INTERNAL_ERROR
                  message: Internal server error
                  hint: Contact support@backworkhealth.com with the request_id from this response
                  docUrl: https://backworkhealth.com/docs/errors#server-internal-error
                  retryable: false
                meta:
                  request_id: req_abc123
                  timestamp: '2024-01-15T10:30:00Z'
    servers:
    - url: https://backworkhealth.com/api/v1
      description: Production server
    - url: http://localhost:3000/api/v1
      description: Local development
components:
  schemas:
    CertifiedDecisionResponseMeta:
      type: object
      properties:
        request_id:
          type: string
          description: Unique request identifier for tracing
        timestamp:
          type: string
          format: date-time
          description: Response timestamp
        pagination:
          $ref: '#/components/schemas/CertifiedDecisionPaginationMeta'
        release_id:
          type: string
          pattern: ^bwr_[0-9a-f]{64}$
          description: Content-addressed release ID
        release_manifest_sha256:
          $ref: '#/components/schemas/Sha256Digest'
        dataset_sha256:
          $ref: '#/components/schemas/Sha256Digest'
        source_set_sha256:
          $ref: '#/components/schemas/Sha256Digest'
        qa_certification_sha256:
          description: Digest of the external QA certification evidence bound to the release
          $ref: '#/components/schemas/Sha256Digest'
        rights_evidence_sha256:
          description: Digest of the external commercial-rights evidence bound to the release
          $ref: '#/components/schemas/Sha256Digest'
        qa_status:
          type: string
          const: certified
        rights_status:
          type: string
          const: approved
        field_profile:
          type: string
          const: derived_decision_v1
        release_schema_version:
          type: string
          const: certified_release.v1
          description: Exact wire contract for this release surface
        source_as_of:
          type: string
          format: date-time
          description: Latest source-data instant represented by the snapshot
        expires_at:
          type: string
          format: date-time
          description: Release availability expires before this instant
        certified_at:
          type: string
          format: date-time
        rights_approved_at:
          type: string
          format: date-time
        release_created_at:
          type: string
          format: date-time
      required:
      - request_id
      - timestamp
      - pagination
      - release_id
      - release_manifest_sha256
      - dataset_sha256
      - source_set_sha256
      - qa_certification_sha256
      - rights_evidence_sha256
      - qa_status
      - rights_status
      - field_profile
      - release_schema_version
      - source_as_of
      - expires_at
      - certified_at
      - rights_approved_at
      - release_created_at
    JsonArray:
      type: array
      items:
        $ref: '#/components/schemas/JsonValue'
    CertifiedDecision:
      type: object
      properties:
        decision_id:
          type: string
          pattern: ^bwd_[0-9a-f]{64}$
          description: Content-addressed decision ID; equal to `bwd_` plus `record_sha256`
        record_sha256:
          description: Digest of the canonical released decision record
          $ref: '#/components/schemas/Sha256Digest'
        policy_id:
          type: string
          minLength: 1
          description: Source policy identifier
        policy_version:
          type: integer
          minimum: 1
          description: Pinned source policy version
        policy_fingerprint_sha256:
          description: Digest binding the decision to the exact source policy version
          $ref: '#/components/schemas/Sha256Digest'
        source_document_sha256:
          description: Digest of the immutable source document used for the decision
          $ref: '#/components/schemas/Sha256Digest'
        payer_code:
          type: string
          minLength: 1
          maxLength: 100
          pattern: ^[A-Z0-9][A-Z0-9_.-]{0,99}$
          description: Canonical uppercase payer code
        line_of_business:
          type: string
          enum:
          - commercial
          - medicare
          - medicaid
          - exchange
        code_system:
          type: string
          enum:
          - CPT
          - HCPCS
          - ICD10CM
          - ICD10PCS
        code:
          type: string
          minLength: 1
          maxLength: 20
          pattern: ^[A-Z0-9.]+$
          description: Canonical uppercase code valid for `code_system`
        disposition:
          type: string
          enum:
          - covered
          - not_covered
          - requires_pa
          - conditional
        effective_date:
          type: string
          format: date
        retire_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
      required:
      - decision_id
      - record_sha256
      - policy_id
      - policy_version
      - policy_fingerprint_sha256
      - source_document_sha256
      - payer_code
      - line_of_business
      - code_system
      - code
      - disposition
      - effective_date
      - retire_date
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          properties:
            code:
              $ref: '#/components/schemas/ApiErrorCode'
            message:
              type: string
              description: Human-readable error message
            hint:
              description: Suggestion for resolving the error
              type: string
            docUrl:
              description: Link to error documentation
              type: string
              format: uri
            retryable:
              type: boolean
              description: Whether repeating the identical request later can succeed
            details:
              description: Additional error details
              $ref: '#/components/schemas/JsonValue'
          required:
          - code
          - message
          - retryable
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
      - success
      - error
      - meta
    ApiErrorCode:
      type: string
      enum:
      - AUTH_MISSING
      - AUTH_INVALID_FORMAT
      - AUTH_INVALID_KEY_FORMAT
      - AUTH_INVALID_TOKEN
      - AUTH_KEY_NOT_FOUND
      - AUTH_KEY_REVOKED
      - AUTH_KEY_SUSPENDED
      - AUTH_KEY_EXPIRED
      - AUTH_SANDBOX_TEST_KEY_REQUIRED
      - AUTH_TEST_KEY_SANDBOX_ONLY
      - AUTHZ_SCOPE_REQUIRED
      - AUTHZ_IP_NOT_ALLOWED
      - AUTHZ_ORIGIN_NOT_ALLOWED
      - BILLING_FEATURE_REQUIRED
      - BILLING_CREDITS_EXHAUSTED
      - RATE_LIMIT_EXCEEDED
      - RATE_QUOTA_EXCEEDED
      - RATE_CONCURRENT_EXCEEDED
      - VALIDATION_ERROR
      - VALIDATION_INVALID_JSON
      - VALIDATION_REQUIRED_FIELD
      - VALIDATION_OUT_OF_RANGE
      - VALIDATION_INVALID_FORMAT
      - PHI_NOT_ALLOWED
      - RESOURCE_NOT_FOUND
      - RESOURCE_POLICY_NOT_FOUND
      - RESOURCE_CODE_NOT_FOUND
      - RESOURCE_JURISDICTION_NOT_FOUND
      - RESOURCE_PAYER_NOT_FOUND
      - RESOURCE_RELEASE_NOT_AVAILABLE
      - REQUEST_INVALID_CURSOR
      - REQUEST_IDEMPOTENCY_CONFLICT
      - REQUEST_IDEMPOTENCY_IN_PROGRESS
      - REQUEST_UNSUPPORTED_CONTENT_TYPE
      - REQUEST_FORMAT_NOT_ACCEPTABLE
      - SERVER_INTERNAL_ERROR
      - SERVER_DATABASE_ERROR
      - SERVER_SEARCH_UNAVAILABLE
      - SERVER_TIMEOUT
      - SERVER_UNAVAILABLE
      - SERVER_IDEMPOTENCY_UNAVAILABLE
      - SERVER_UPSTREAM_UNAVAILABLE
      - COMMERCIAL_SURFACE_UNAVAILABLE
      description: Machine-readable error code
    ResponseMeta:
      type: object
      properties:
        request_id:
          type: string
          description: Unique request identifier for tracing
        timestamp:
          type: string
          format: date-time
          description: Response timestamp
      required:
      - request_id
      - timestamp
    GateDenialResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - INVALID_API_KEY
              - SUBSCRIPTION_INACTIVE
              - FEATURE_NOT_AVAILABLE
              - USAGE_LIMIT_EXCEEDED
              - DAILY_LIMIT_EXCEEDED
            message:
              type: string
              description: Which limit or feature check failed, when it resets, and who can manage the plan
          required:
          - code
          - message
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
      - success
      - error
      - meta
      description: The plan does not include this feature or its usage is exhausted.
    JsonObject:
      type: object
      propertyNames:
        type: string
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
    Sha256Digest:
      type: string
      minLength: 64
      maxLength: 64
      pattern: ^[0-9a-f]{64}$
      description: Lowercase hexadecimal SHA-256 digest
    JsonValue:
      anyOf:
      - type: string
      - type: number
      - type: boolean
      - type: 'null'
      - $ref: '#/components/schemas/JsonArray'
      - $ref: '#/components/schemas/JsonObject'
      description: Any JSON value.
    CertifiedDecisionPaginationMeta:
      type: object
      properties:
        cursor:
          anyOf:
          - type: string
            pattern: ^bwd_[0-9a-f]{64}$
          - type: 'null'
          description: Decision ID to pass as `cursor`; null when no next page exists
        has_more:
          type: boolean
        limit:
          type: integer
          minimum: 1
          maximum: 100
      required:
      - cursor
      - has_more
      - limit
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API key in format: bwk_live_xxxxx. Keys issued before the rename (vrt_live_) remain valid. bwk_test_ keys work only on the sandbox.'
x-refined-from:
- backworkhealth-com-openapi.json
- backworkhealth-com-v1-openapi.json