openapi: 3.0.3
info:
  title: OTR Trust Verification API
  description: 查询域名的OTR信任评分和信号明细
  version: 1.0.0
  contact:
    name: ORBEXA
    url: https://orbexa.io

servers:
  - url: https://orbexa.io
    description: 生产环境

paths:
  /api/otr/verify/{domain}:
    get:
      summary: 查询域名信任评分
      description: 返回指定域名的六维度信任评分、信号明细和实体数据
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
          description: 要查询的域名（不含协议前缀）
          example: example.com
      responses:
        '200':
          description: 成功返回信任评分数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustReport'
        '404':
          description: 域名未找到
        '429':
          description: 请求频率超限

  /.well-known/otr/verify/{domain}:
    get:
      summary: .well-known端点（与主API相同）
      description: 符合RFC 8615的服务发现端点，返回与主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: 查询的域名
        name:
          type: string
          description: 商家名称
        trust_score:
          type: number
          minimum: 0
          maximum: 100
          description: 综合信任评分
        badge:
          type: string
          enum: [PLATINUM, GOLD, SILVER, BRONZE, UNRATED]
          description: 信任徽章
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        entity_data:
          type: object
          description: 第三方验证的实体信息
        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: 信号具体值
        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