> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OTR OpenAPI 3.0 specification and SDK generation

> The OpenAPI 3.0 specification for the OTR verification API — endpoint definitions, data models, SDK generation, and usage examples.

# OpenAPI Specification

## 8.1 OpenAPI 3.0 Overview

The OTR REST API conforms to the [OpenAPI 3.0](https://swagger.io/specification/) specification. OpenAPI is a standardized API description format that enables:

* Automatic client SDK generation (TypeScript, Python, Go, and more)
* Interactive API documentation
* Automated API testing
* Import into tools such as Postman

## 8.2 OTR API Specification

```yaml theme={null}
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
```

## 8.3 Generating SDKs from the OpenAPI Spec

### TypeScript

```bash theme={null}
npx openapi-typescript-codegen --input otr-api.yaml --output ./src/otr-client
```

### Python

```bash theme={null}
pip install openapi-python-client
openapi-python-client generate --path otr-api.yaml
```

## 8.4 Importing into Postman

1. Open Postman and go to **Import**, then select the OpenAPI file
2. Postman automatically creates a request collection
3. Test each endpoint directly from the collection

***

**Next chapter**: [Agent Integration Patterns](/en/book-2/ch9-agent-integration) — How AI agents integrate OTR trust queries into their decision-making