satoshidata-ai Feedback API

openapi: 3.2.0
info:
  title: Satoshidata Agent Feedback API
  description: Bitcoin agent API with chain intelligence, Bitcoin timestamping, and machine-readable discovery. Public beta general access is free while documented conditional limits, including Wallet P&L above 100 transactions outside the public showcase, remain active. The checkout code path is preserved for the post-beta access model.
  version: 0.3.0
tags:
- name: Feedback
paths:
  /v1/feedback:
    post:
      tags:
      - Feedback
      summary: Submit machine-readable feedback or data corrections
      description: Free machine-readable label corrections, missing-label suggestions, data-quality reports, or general feedback.
      operationId: submit_feedback
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackSubmitRequest'
        required: true
      responses:
        '200':
          description: Submit feedback
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitFeedbackResponse'
        '422':
          description: Request validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ErrorResponse'
                - $ref: '#/components/schemas/RouteRecoveryResponse'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-satoshidata-pricing:
        capability: feedback_submit
        access_tier: free
        live_access_model: free
        target_access_model: free
        future_native_l402_price_sats: 0
        price_unit: request
      x-satoshidata-surface:
        canonical_name: submit_feedback
        pricing_capability: feedback_submit
        access_tier: free
        mcp_mode: live
components:
  schemas:
    RouteRecoveryResponse:
      type: object
      description: Typo-friendly 404 help card returned when a missing GET /v1 path closely matches a documented endpoint.
      properties:
        error:
          type: string
          const: route_recovery
          description: Machine-readable recovery envelope marker.
        detail:
          type: string
          description: Human-readable explanation naming the likely intended route.
        did_you_mean:
          type: string
          description: Canonical documented endpoint path that most closely matches the request.
        docs_url:
          type: string
          description: OpenAPI document URL for route discovery.
        alternatives:
          type: array
          description: Additional close documented endpoint matches when more than one is plausible.
          items:
            type: string
        beta:
          type: boolean
          description: True when the public beta envelope is active.
      required:
      - error
      - detail
      - did_you_mean
      - docs_url
    ResponsePagination:
      additionalProperties: false
      properties:
        offset:
          title: Offset
          type: integer
        limit:
          title: Limit
          type: integer
        total_alerts:
          title: Total Alerts
          type: integer
        next_offset:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Offset
        has_more:
          title: Has More
          type: boolean
      required:
      - offset
      - limit
      - total_alerts
      - next_offset
      - has_more
      title: ResponsePagination
      type: object
    SubmitFeedbackResponse:
      additionalProperties: false
      properties:
        ok:
          title: Ok
          type: boolean
        feedback_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Feedback Id
        stored:
          title: Stored
          type: boolean
        rate_limit:
          anyOf:
          - $ref: '#/components/schemas/RateLimitProjection'
          - type: 'null'
          default: null
        _meta:
          $ref: '#/components/schemas/ResponseMeta'
        beta:
          title: Beta
          type: boolean
      required:
      - ok
      - stored
      - _meta
      - beta
      title: SubmitFeedbackResponse
      type: object
    ResponseWarning:
      additionalProperties: false
      properties:
        code:
          title: Code
          type: string
        message:
          title: Message
          type: string
      required:
      - code
      - message
      title: ResponseWarning
      type: object
    FeedbackSubmitRequest:
      properties:
        type:
          type: string
          enum:
          - label_correction
          - label_missing
          - data_quality
          - general
          - general_feedback
          title: Type
          description: 'Allowed values: label_correction, label_missing, data_quality, general, general_feedback.'
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        current_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Label
        suggested_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Suggested Label
        suggested_category:
          anyOf:
          - type: string
          - type: 'null'
          title: Suggested Category
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        confidence:
          anyOf:
          - type: string
          - type: 'null'
          title: Confidence
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
        summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Alias for summary for general feedback.
        endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint
        severity:
          anyOf:
          - type: string
          - type: 'null'
          enum:
          - info
          - low
          - medium
          - high
          - critical
          title: Severity
          description: Optional triage severity for general feedback.
        category:
          anyOf:
          - type: string
          - type: 'null'
          enum:
          - api_design
          - docs
          - data_quality
          - label_correction
          - bug
          - other
          title: Category
          description: Optional category for general feedback.
        asks:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Asks
      type: object
      required:
      - type
      title: FeedbackSubmitRequest
    ResponseMetaDetail:
      type: object
      description: Machine-readable metadata added by satoshidata.ai JSON responses.
      additionalProperties: false
      properties:
        endpoint:
          type: string
          description: Canonical request path.
        freshness:
          type: string
          description: Best-known freshness timestamp for the payload.
        freshness_semantics:
          type: string
          enum:
          - internal_refresh
          - source_poll
          - claim_made
          description: 'Meaning of _meta.freshness for this response: internal_refresh, source_poll, or claim_made.'
        source:
          type: string
          description: Primary data source for the response.
        price_sats:
          type: integer
          description: Native BTC-denominated price for this response, when applicable.
        docs:
          type: string
          description: OpenAPI documentation URL.
        warnings:
          type: array
          description: Non-fatal response warnings. Empty when no caveat applies.
          items:
            $ref: '#/components/schemas/ResponseWarning'
        pagination:
          type: object
          description: Pagination metadata when an endpoint supports paged archive traversal.
          additionalProperties: false
          properties:
            offset:
              type: integer
              minimum: 0
            limit:
              type: integer
              minimum: 1
            total_alerts:
              type: integer
              minimum: 0
            next_offset:
              anyOf:
              - type: integer
                minimum: 0
              - type: 'null'
            has_more:
              type: boolean
          required:
          - offset
          - limit
          - total_alerts
          - next_offset
          - has_more
        field_semantics:
          type: object
          description: Machine-readable notes explaining field-level semantics for the payload.
          additionalProperties: true
        semantic_completeness:
          type: object
          description: Machine-readable completeness caveats for fields that can be partial or derived.
          additionalProperties: true
        price_usd:
          type: string
          description: USD-denominated x402 price when a per-call grant was used.
        view:
          type: string
          enum:
          - compact
          description: Response projection view, currently compact.
        bitcoin_backend:
          type: string
          description: Public label for the Bitcoin backend used by the response.
        beta:
          type: boolean
          description: Endpoint-specific beta flag when carried inside _meta.
        cache_seconds:
          type: integer
          description: Advertised response cache lifetime in seconds.
        cache_ttl_seconds:
          type: integer
          description: Advertised response cache TTL in seconds.
        cache_status:
          type: string
          description: Cache hit/miss/fresh/stale status for cached projections.
        cache_age_seconds:
          type: number
          description: Age in seconds for the cached projection served.
        cache_cached_at:
          type: string
          description: Timestamp when the served projection was cached.
        cached:
          type: boolean
          description: True when this response body came from a cache.
        cache_policy:
          type: string
          description: Stable cache policy label for the response.
        compute_ms:
          type: integer
          description: Server-side compute time in milliseconds.
        warning:
          type: string
          description: Single human-readable response warning when a legacy slot is used.
        refresh_warning:
          type: string
          description: Warning about background refresh state for cached dashboard data.
        last_refresh_started_at:
          type: string
          description: Timestamp for the last background refresh start.
        last_refresh_completed_at:
          type: string
          description: Timestamp for the last background refresh completion.
        last_refresh_status:
          type: string
          description: Status of the last background refresh.
        last_refresh_error:
          type: string
          description: Last background refresh error, when present.
        last_refresh_duration_ms:
          type: integer
          description: Last background refresh duration in milliseconds.
        feature_flag:
          type: string
          description: Runtime feature flag associated with an experimental endpoint.
        rollout_state:
          type: string
          description: Rollout state for hidden or beta backend features.
        schema_version:
          anyOf:
          - type: string
          - type: 'null'
          description: Endpoint-specific payload schema version, when declared.
        retention:
          type: string
          description: Retention policy label for ephemeral response artifacts.
        not_compliance_advice:
          type: boolean
          description: True when the response is explicitly not compliance advice.
        future_native_price_mode:
          type: string
          description: Future native-pricing mode for endpoints with dynamic fees.
        future_native_price_note:
          type: string
          description: Human-readable note for future native-pricing mode.
        future_native_quote_endpoint:
          type: string
          description: Endpoint that quotes a future dynamic native price.
        overview_activity_cache:
          type: object
          description: Metadata for wallet overview directional-activity cache reuse.
          additionalProperties: true
        attribution_confidence:
          type: string
          description: Attribution confidence label for pool-intel metadata.
        generated_at:
          type: string
          description: Timestamp when the source projection was generated.
        last_computed:
          type: string
          description: Timestamp when the source projection was last computed.
        snapshot_generated_at:
          type: string
          description: Timestamp embedded in the served persistent snapshot.
        snapshot_age_seconds:
          type: number
          description: Age in seconds for the served persistent snapshot.
        snapshot_stale_after_seconds:
          type: integer
          description: Staleness threshold in seconds for the served persistent snapshot.
        snapshot_status:
          type: string
          description: Freshness status for the served persistent snapshot.
        history_window_basis:
          type: string
          description: History-window basis used by pool-intel projections.
        history_window_start_height:
          type: integer
          description: Earliest block height covered by the pool-intel history window.
        first_block_mined_coverage:
          type: string
          description: Whether first_block_mined is full-history or partial-window constrained.
        first_block_mined_note:
          type: string
          description: Coverage caveat for first_block_mined when history is partial.
        total_blocks_last_24h:
          type: integer
          description: Pool-intel total block count in the current 24h window.
    RateLimitProjection:
      additionalProperties: false
      properties:
        limit:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Limit
        remaining:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Remaining
        reset_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Reset At
        bucket:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Bucket
      title: RateLimitProjection
      type: object
    ResponseMeta:
      additionalProperties: false
      properties:
        endpoint:
          title: Endpoint
          type: string
        freshness:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Freshness
        freshness_semantics:
          anyOf:
          - enum:
            - internal_refresh
            - source_poll
            - claim_made
            type: string
          - type: 'null'
          default: null
          title: Freshness Semantics
        source:
          title: Source
          type: string
        price_sats:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Price Sats
        price_usd:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Price Usd
        docs:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Docs
        warnings:
          items:
            $ref: '#/components/schemas/ResponseWarning'
          title: Warnings
          type: array
        pagination:
          anyOf:
          - $ref: '#/components/schemas/ResponsePagination'
          - type: 'null'
          default: null
        view:
          anyOf:
          - const: compact
            type: string
          - type: 'null'
          default: null
          title: View
        bitcoin_backend:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Bitcoin Backend
        beta:
          anyOf:
          - type: boolean
          - type: 'null'
          default: null
          title: Beta
        cache_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Cache Seconds
        cache_ttl_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Cache Ttl Seconds
        cache_status:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Cache Status
        cache_age_seconds:
          anyOf:
          - type: number
          - type: 'null'
          default: null
          title: Cache Age Seconds
        cache_cached_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Cache Cached At
        cached:
          anyOf:
          - type: boolean
          - type: 'null'
          default: null
          title: Cached
        cache_policy:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Cache Policy
        compute_ms:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Compute Ms
        warning:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Warning
        refresh_warning:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Refresh Warning
        last_refresh_started_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Last Refresh Started At
        last_refresh_completed_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Last Refresh Completed At
        last_refresh_status:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Last Refresh Status
        last_refresh_error:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Last Refresh Error
        last_refresh_duration_ms:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Last Refresh Duration Ms
        feature_flag:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Feature Flag
        rollout_state:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Rollout State
        schema_version:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Schema Version
        methodology_version:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Methodology Version
        materialized_source:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Materialized Source
        max_hops:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Max Hops
        retention:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Retention
        not_compliance_advice:
          anyOf:
          - type: boolean
          - type: 'null'
          default: null
          title: Not Compliance Advice
        future_native_price_mode:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Future Native Price Mode
        future_native_price_note:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Future Native Price Note
        future_native_quote_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Future Native Quote Endpoint
        overview_activity_cache:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          title: Overview Activity Cache
        attribution_confidence:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Attribution Confidence
        generated_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Generated At
        last_computed:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Last Computed
        snapshot_generated_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Snapshot Generated At
        snapshot_age_seconds:
          anyOf:
          - type: number
          - type: 'null'
          default: null
          title: Snapshot Age Seconds
        snapshot_stale_after_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Snapshot Stale After Seconds
        snapshot_status:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Snapshot Status
        history_window_basis:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: History Window Basis
        total_blocks_last_24h:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Total Blocks Last 24H
        field_semantics:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          title: Field Semantics
        semantic_completeness:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          title: Semantic Completeness
      required:
      - endpoint
      - source
      title: ResponseMeta
      type: object
    ErrorResponse:
      type: object
      description: Error response envelope.
      additionalProperties: false
      properties:
        detail:
          description: Human-readable error detail or structured problem detail.
          anyOf:
          - type: string
          - type: object
            additionalProperties: true
          - type: 'null'
        errors:
          type: array
          description: Structured validation errors when request validation fails.
          items:
            type: object
            additionalProperties: true
        beta:
          type: boolean
          description: True when the public beta envelope is active.
        _meta:
          $ref: '#/components/schemas/ResponseMetaDetail'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-WR-API-Key