openapi: 3.0.3
info:
  title: OTR Trust Verification API
  description: Query a domain's OTR trust score and signal details
  version: 1.0.0
  contact:
    name: ORBEXA
    url: https://orbexa.io

servers:
  - url: https://orbexa.io
    description: Production

paths:
  /api/otr/verify/{domain}:
    get:
      summary: Query domain trust score
      description: Returns the six-dimension trust score, signal details, and entity data for the specified domain
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
          description: The domain to query (without protocol prefix)
          example: example.com
      responses:
        '200':
          description: Trust score data returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustReport'
        '404':
          description: Domain not found
        '429':
          description: Rate limit exceeded

  /.well-known/otr/verify/{domain}:
    get:
      summary: Well-known endpoint (identical to primary API)
      description: RFC 8615-compliant service discovery endpoint returning the same data as the primary API
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustReport'

components:
  schemas:
    TrustReport:
      type: object
      properties:
        domain:
          type: string
          description: The queried domain
        name:
          type: string
          description: Merchant name
        trust_score:
          type: number
          minimum: 0
          maximum: 100
          description: Composite trust score
        badge:
          type: string
          enum: [PLATINUM, GOLD, SILVER, BRONZE, UNRATED]
          description: Trust badge
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        entity_data:
          type: object
          description: Third-party verified entity information
        agent_commerce:
          $ref: '#/components/schemas/AgentCommerce'
        scanned_at:
          type: string
          format: date-time
        otr_id:
          type: string

    Dimensions:
      type: object
      properties:
        V:
          $ref: '#/components/schemas/DimensionScore'
        S:
          $ref: '#/components/schemas/DimensionScore'
        G:
          $ref: '#/components/schemas/DimensionScore'
        T:
          $ref: '#/components/schemas/DimensionScore'
        D:
          $ref: '#/components/schemas/DimensionScore'
        F:
          $ref: '#/components/schemas/DimensionScore'

    DimensionScore:
      type: object
      properties:
        score:
          type: number
          nullable: true
        signals:
          type: array
          items:
            $ref: '#/components/schemas/Signal'

    Signal:
      type: object
      properties:
        signal_name:
          type: string
        status:
          type: string
          enum: [detected, not_found, not_scanned, fetch_failed]
        value:
          description: The signal's concrete value
        evidence:
          type: string
        source_url:
          type: string

    AgentCommerce:
      type: object
      properties:
        llms_txt:
          type: boolean
        agent_json:
          type: boolean
        schema_org_product:
          type: boolean
        sitemap:
          type: boolean

npx openapi-typescript-codegen --input otr-api.yaml --output ./src/otr-client

pip install openapi-python-client
openapi-python-client generate --path otr-api.yaml