DefaultBench Evidence API

openapi: 3.2.0
info:
  title: DefaultBench Evidence API
  version: 1.0.0
  summary: Machine-first paid placement and discovery for autonomous agents.
  description: DefaultBench exposes transparent sponsored rankings. Listings are ordered by cumulative verified USDC payment descending, then by the time the current cumulative total was reached ascending. Rank is paid placement, not an endorsement or quality signal. Monetary values are decimal strings containing integer USDC base units (six decimals).
  termsOfService: https://defaultbench.com/terms
  license:
    name: Proprietary service API; public protocol documentation
    url: https://defaultbench.com/terms
servers:
- url: https://defaultbench.com
  description: Configured DefaultBench origin
tags:
- name: Evidence
  description: Bounded observations and declared provenance. Evidence is not trust, safety, quality, or endorsement.
paths:
  /api/v1/evidence/{subjectType}/{id}/history:
    get:
      operationId: getEvidenceHistory
      tags:
      - Evidence
      summary: Read resource evidence and metadata-change history
      description: Returns timestamped measured observations, derived 30-day reliability, and source/advertiser declarations. It never performs a live probe.
      parameters:
      - name: subjectType
        in: path
        required: true
        schema:
          type: string
          enum:
          - organic
          - sponsored
      - $ref: '#/components/parameters/ListingId'
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Bounded evidence history.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceHistory'
        '400':
          description: The request is malformed or a query parameter is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidKeyword:
                  value:
                    error:
                      code: invalid_keyword
                      message: Keyword must normalize to 1–64 valid characters.
                      details: {}
                validationError:
                  value:
                    error:
                      code: validation_error
                      message: Request validation failed.
                      details:
                        fields:
                        - path: limit
                          message: 'Too big: expected number to be <=100'
        '404':
          description: The requested resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: not_found
                  message: The requested resource was not found.
                  details: {}
        '429':
          description: The applicable bounded rate limit is exhausted.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Rate limit exceeded. Retry after the indicated delay.
                  details: {}
                  retry_after_seconds: 30
        '500':
          description: An unexpected server error occurred; no uncertain payment is credited.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: The request could not be completed.
                  details: {}
        '503':
          description: A dependency is unavailable, one identical request owns the settlement claim, settlement is uncertain, or a confirmed settlement is awaiting atomic ranking credit. These responses never authorize a replacement payment. Retry the identical paid request after Retry-After unless the code says otherwise.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            PAYMENT-RESPONSE:
              $ref: '#/components/headers/PaymentResponse'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                dependencyUnavailable:
                  value:
                    error:
                      code: service_unavailable
                      message: A required dependency is temporarily unavailable.
                      details:
                        retryable: true
                settlementInProgress:
                  value:
                    error:
                      code: payment_settlement_in_progress
                      message: An identical settlement attempt is already in progress. Retry this request shortly.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        settlement_state: settling
                        transaction_id: null
                        retryable: true
                settlementUncertain:
                  value:
                    error:
                      code: payment_settlement_uncertain
                      message: The settlement outcome is being reconciled and will not be submitted again automatically. Retry this identical request for the durable result.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        settlement_state: settlement_uncertain
                        transaction_id: null
                        retryable: true
                settledPendingCredit:
                  value:
                    error:
                      code: payment_settled_pending_credit
                      message: Settlement succeeded, but ranking credit is pending durable recovery. Retry the identical request.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        transaction_id: '0x0000000000000000000000000000000000000000000000000000000000000001'
                        retryable: true
                bidConfigurationUnavailable:
                  value:
                    error:
                      code: bid_configuration_unavailable
                      message: Bidding is temporarily unavailable while payment policy configuration is synchronized.
                      details:
                        retryable: true
  /api/v1/compare:
    get:
      operationId: compareResources
      tags:
      - Evidence
      summary: Compare two to five sponsored or organic resources
      parameters:
      - name: resources
        in: query
        required: true
        description: Comma-separated organic:<uuid> or sponsored:<uuid> values.
        schema:
          type: string
          minLength: 2
          maxLength: 512
      responses:
        '200':
          description: Side-by-side declared and measured evidence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComparisonResponse'
        '400':
          description: The request is malformed or a query parameter is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidKeyword:
                  value:
                    error:
                      code: invalid_keyword
                      message: Keyword must normalize to 1–64 valid characters.
                      details: {}
                validationError:
                  value:
                    error:
                      code: validation_error
                      message: Request validation failed.
                      details:
                        fields:
                        - path: limit
                          message: 'Too big: expected number to be <=100'
        '404':
          description: The requested resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: not_found
                  message: The requested resource was not found.
                  details: {}
        '429':
          description: The applicable bounded rate limit is exhausted.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Rate limit exceeded. Retry after the indicated delay.
                  details: {}
                  retry_after_seconds: 30
        '500':
          description: An unexpected server error occurred; no uncertain payment is credited.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: The request could not be completed.
                  details: {}
        '503':
          description: A dependency is unavailable, one identical request owns the settlement claim, settlement is uncertain, or a confirmed settlement is awaiting atomic ranking credit. These responses never authorize a replacement payment. Retry the identical paid request after Retry-After unless the code says otherwise.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            PAYMENT-RESPONSE:
              $ref: '#/components/headers/PaymentResponse'
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                dependencyUnavailable:
                  value:
                    error:
                      code: service_unavailable
                      message: A required dependency is temporarily unavailable.
                      details:
                        retryable: true
                settlementInProgress:
                  value:
                    error:
                      code: payment_settlement_in_progress
                      message: An identical settlement attempt is already in progress. Retry this request shortly.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        settlement_state: settling
                        transaction_id: null
                        retryable: true
                settlementUncertain:
                  value:
                    error:
                      code: payment_settlement_uncertain
                      message: The settlement outcome is being reconciled and will not be submitted again automatically. Retry this identical request for the durable result.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        settlement_state: settlement_uncertain
                        transaction_id: null
                        retryable: true
                settledPendingCredit:
                  value:
                    error:
                      code: payment_settled_pending_credit
                      message: Settlement succeeded, but ranking credit is pending durable recovery. Retry the identical request.
                      details:
                        idempotency_key: bid_01JQ4Z6W2YW1FVD5QAPGMF6M4Q
                        transaction_id: '0x0000000000000000000000000000000000000000000000000000000000000001'
                        retryable: true
                bidConfigurationUnavailable:
                  value:
                    error:
                      code: bid_configuration_unavailable
                      message: Bidding is temporarily unavailable while payment policy configuration is synchronized.
                      details:
                        retryable: true
  /api/v1/benchmarks/v1/manifest:
    get:
      operationId: getBenchmarkManifestV1
      tags:
      - Evidence
      summary: Read the versioned safe-conformance benchmark manifest
      responses:
        '200':
          description: Static V1 manifest; arbitrary execution and payments are forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenchmarkManifestV1'
components:
  schemas:
    ComparisonResponse:
      type: object
      additionalProperties: false
      required:
      - resources
      - comparison_basis
      - sponsored_order_affected
      - disclaimer
      properties:
        resources:
          type: array
          minItems: 2
          maxItems: 5
          items:
            type: object
            additionalProperties: false
            required:
            - type
            - id
            - name
            - evidence
            properties:
              type:
                type: string
                enum:
                - organic
                - sponsored
              id:
                type: string
                format: uuid
              name:
                type: string
              evidence:
                $ref: '#/components/schemas/EvidenceSummary'
        comparison_basis:
          type: string
        sponsored_order_affected:
          type: boolean
          const: false
        disclaimer:
          type: string
    EvidenceReliability:
      type: object
      additionalProperties: false
      required:
      - sample_count
      - window_days
      - success_rate
      - latency_p50_ms
      - latency_p95_ms
      - last_observed_at
      - last_successful_observation_at
      - consecutive_failures
      - freshness
      - origin
      properties:
        sample_count:
          type: integer
          minimum: 0
        window_days:
          type: integer
          const: 30
        success_rate:
          oneOf:
          - type: string
            pattern: ^(?:0(?:\.\d+)?|1(?:\.0+)?)$
          - type: 'null'
        latency_p50_ms:
          oneOf:
          - type: string
            pattern: ^\d+(?:\.\d+)?$
          - type: 'null'
        latency_p95_ms:
          oneOf:
          - type: string
            pattern: ^\d+(?:\.\d+)?$
          - type: 'null'
        last_observed_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
        last_successful_observation_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
        consecutive_failures:
          type: integer
          minimum: 0
        freshness:
          type: string
          enum:
          - fresh
          - aging
          - stale
          - not_observed
        origin:
          type: string
          enum:
          - derived
          - not_observed
    EvidenceObservation:
      type: object
      additionalProperties: false
      required:
      - id
      - run_id
      - manifest_version
      - check_kind
      - endpoint_kind
      - endpoint_url
      - checked_at
      - outcome
      - counts_toward_reliability
      - availability_success
      - http_status
      - latency_ms
      - response_bytes
      - response_sha256
      - resolved_address_count
      - redirect_count
      - tls
      - conformance
      - error_category
      - claim_origin
      properties:
        id:
          type: string
          format: uuid
        run_id:
          type: string
          format: uuid
        manifest_version:
          type: string
          const: 1.0.0
        check_kind:
          type: string
          enum:
          - availability
          - tls
          - a2a
          - mcp
          - openapi
          - llms_txt
          - x402
        endpoint_kind:
          type: string
        endpoint_url:
          type: string
          format: uri
          pattern: ^https://
        checked_at:
          type: string
          format: date-time
        outcome:
          type: string
          enum:
          - passed
          - failed
          - not_observed
        counts_toward_reliability:
          type: boolean
        availability_success:
          oneOf:
          - type: boolean
          - type: 'null'
        http_status:
          oneOf:
          - type: integer
            minimum: 100
            maximum: 599
          - type: 'null'
        latency_ms:
          oneOf:
          - type: integer
            minimum: 0
          - type: 'null'
        response_bytes:
          oneOf:
          - type: integer
            minimum: 0
          - type: 'null'
        response_sha256:
          oneOf:
          - type: string
            pattern: ^[0-9a-f]{64}$
          - type: 'null'
        resolved_address_count:
          type: integer
          minimum: 0
        redirect_count:
          type: integer
          minimum: 0
          maximum: 2
        tls:
          type: object
        conformance:
          type: object
        error_category:
          oneOf:
          - type: string
            maxLength: 64
          - type: 'null'
        claim_origin:
          type: string
          const: measured
    EvidenceHistory:
      type: object
      additionalProperties: false
      required:
      - subject_type
      - subject_id
      - summary
      - observations
      - metadata_changes
      - next_cursor
      properties:
        subject_type:
          type: string
          enum:
          - organic
          - sponsored
        subject_id:
          type: string
          format: uuid
        summary:
          $ref: '#/components/schemas/EvidenceSummary'
        observations:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/EvidenceObservation'
        metadata_changes:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/MetadataChange'
        next_cursor:
          oneOf:
          - type: string
          - type: 'null'
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
          - code
          - message
          - details
          properties:
            code:
              type: string
              pattern: ^[a-z][a-z0-9_]*$
              description: Stable machine-readable code.
            message:
              type: string
              description: Human-readable, non-stable explanation.
            details:
              $ref: '#/components/schemas/ErrorDetail'
            retry_after_seconds:
              type: integer
              minimum: 1
    EvidenceSummary:
      type: object
      additionalProperties: false
      required:
      - profile_id
      - subject_type
      - source_registry
      - source_url
      - first_seen_at
      - last_seen_at
      - verified_domain
      - domain_verified_at
      - canonical_endpoints
      - declared_protocols
      - declared_tools
      - declared_categories
      - declared_pricing
      - declared_payment_networks
      - source_metadata_hash
      - source_metadata_changed_at
      - declaration_origin
      - domain_origin
      - reliability
      - disclaimer
      properties:
        profile_id:
          oneOf:
          - type: string
            format: uuid
          - type: 'null'
        subject_type:
          type: string
          enum:
          - organic
          - sponsored
        source_registry:
          type: string
          maxLength: 160
        source_url:
          $ref: '#/components/schemas/NullableUrl'
        first_seen_at:
          type: string
          format: date-time
        last_seen_at:
          type: string
          format: date-time
        verified_domain:
          oneOf:
          - type: string
            maxLength: 253
          - type: 'null'
        domain_verified_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
        canonical_endpoints:
          type: object
          additionalProperties:
            type: string
            format: uri
            pattern: ^https://
        declared_protocols:
          type: array
          maxItems: 16
          items:
            type: string
        declared_tools:
          type: array
          maxItems: 64
          items:
            type: string
        declared_categories:
          type: array
          maxItems: 64
          items:
            type: string
        declared_pricing:
          type: object
        declared_payment_networks:
          type: array
          maxItems: 32
          items:
            type: string
        source_metadata_hash:
          oneOf:
          - type: string
            pattern: ^[0-9a-f]{64}$
          - type: 'null'
        source_metadata_changed_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
        declaration_origin:
          type: string
          enum:
          - source_declared
          - advertiser_declared
        domain_origin:
          type: string
          enum:
          - verified_control
          - not_observed
        reliability:
          $ref: '#/components/schemas/EvidenceReliability'
        disclaimer:
          type: string
      description: Declared identity/provenance plus derived bounded observations. This is not trust, safety, quality, or endorsement.
    ErrorDetail:
      type: object
      description: Code-specific bounded details; clients must branch on error.code, not message text.
      additionalProperties: true
    BenchmarkManifestV1:
      type: object
      additionalProperties: false
      required:
      - schema
      - id
      - version
      - title
      - scope
      - allowed_checks
      - network_policy
      - limits
      - forbidden
      - semantics
      properties:
        schema:
          type: string
          format: uri
        id:
          type: string
          const: defaultbench-safe-conformance
        version:
          type: string
          const: 1.0.0
        title:
          type: string
        scope:
          type: string
        allowed_checks:
          type: array
          items:
            type: string
            enum:
            - availability
            - tls
            - a2a
            - mcp
            - openapi
            - llms_txt
            - x402
        network_policy:
          type: object
        limits:
          type: object
        forbidden:
          type: array
          items:
            type: string
        semantics:
          type: object
    NullableUrl:
      oneOf:
      - type: string
        format: uri
        pattern: ^https://
        maxLength: 2048
        description: Public HTTPS URL without credentials or a private/loopback-style host.
      - type: 'null'
    MetadataChange:
      type: object
      additionalProperties: false
      required:
      - id
      - previous_hash
      - source_metadata_hash
      - source_metadata
      - observed_at
      - claim_origin
      properties:
        id:
          type: string
          format: uuid
        previous_hash:
          oneOf:
          - type: string
            pattern: ^[0-9a-f]{64}$
          - type: 'null'
        source_metadata_hash:
          type: string
          pattern: ^[0-9a-f]{64}$
        source_metadata:
          type: object
        observed_at:
          type: string
          format: date-time
        claim_origin:
          type: string
          enum:
          - source_declared
          - advertiser_declared
  headers:
    RateLimitRemaining:
      description: Requests remaining in the current policy window.
      schema:
        type: integer
        minimum: 0
    RateLimitLimit:
      description: Maximum requests in the current policy window.
      schema:
        type: integer
        minimum: 1
    PaymentResponse:
      description: Base64-encoded JSON x402 v2 settlement response/receipt. It may also be present on a non-200 facilitator failure or uncertain response; header presence alone is never evidence of success or ranking credit.
      schema:
        type: string
        contentEncoding: base64
    RetryAfter:
      description: Seconds until the caller should retry.
      schema:
        type: integer
        minimum: 1
    RateLimitReset:
      description: Unix epoch timestamp in seconds when the current policy window resets.
      schema:
        type: integer
        minimum: 0
    RequestId:
      description: Opaque request correlation identifier; safe to include in an incident report.
      schema:
        type: string
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum items to return.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    ListingId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    Cursor:
      name: cursor
      in: query
      required: false
      description: Opaque cursor returned by the previous page. Do not inspect or modify it. Omitting it starts a new snapshot traversal.
      schema:
        type: string
        minLength: 1
        maxLength: 512
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: Base64-encoded x402 v2 payment payload. It is intentionally absent on the initial request that obtains HTTP 402 requirements.
    sellerAnalyticsBearer:
      type: http
      scheme: bearer
      bearerFormat: DefaultBench signed token
      description: Five-minute token issued only after consuming a listing-bound, origin-bound EIP-712 wallet challenge.
    operatorBearer:
      type: http
      scheme: bearer
      description: Operator secret for private revenue and purchase-funnel metrics.
externalDocs:
  description: Full autonomous-client instructions
  url: https://defaultbench.com/llms-full.txt
x-defaultbench-payment:
  protocol: x402
  version: 2
  sdkVersion: 2.24.0
  scheme: exact
  network: eip155:8453
  networkLabel: Base mainnet
  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
  symbol: USDC
  decimals: 6
  minimumBidBaseUnits: '10000'
  requestHeader: PAYMENT-SIGNATURE
  challengeHeader: PAYMENT-REQUIRED
  settlementHeader: PAYMENT-RESPONSE
x-defaultbench-ranking:
  primary: cumulative verified payment descending
  tieBreaker: timestamp current cumulative total was reached ascending
  qualitySignal: false
x-defaultbench-examples: Synthetic documentation examples; never production activity.