AimRank Domains API

openapi: 3.2.0
info:
  title: AimRank Domains API
  description: Ranking-as-a-Service API — Turn binary comparisons into calibrated rankings with Glicko-2, Bradley-Terry, TrueSkill, and cross-domain transfer learning. Includes webhooks, API keys, RLHF exports, and embeddable widgets.
  version: 4.12.0
tags:
- name: Domains
paths:
  /api/v1/domains:
    get:
      tags:
      - Domains
      summary: List Domains
      description: List all domains owned by the current user.
      operationId: list_domains_api_v1_domains_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    post:
      tags:
      - Domains
      summary: Create Domain
      description: Create a new domain with optional initial entities.
      operationId: create_domain_api_v1_domains_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDomainRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/domains/search/similar:
    get:
      tags:
      - Domains
      summary: Search Similar Domains
      description: 'Find public domains most similar to a free-text query or a known domain.


        Use ``q`` for free-text similarity (e.g., "pharma evaluation drug

        interactions"). Use ``domain_id`` to find domains similar to one you

        already know about. Exactly one of the two must be supplied.


        Returns a ranked list with cosine similarity score in [0, 1].

        Public endpoint — no auth required. Only public domains are

        searched / returned.'
      operationId: search_similar_domains_api_v1_domains_search_similar_get
      parameters:
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Q
      - name: domain_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Limit
      - name: min_score
        in: query
        required: false
        schema:
          type: number
          default: 0.05
          title: Min Score
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/domains/{domain_id}:
    get:
      tags:
      - Domains
      summary: Get Domain
      description: 'Get domain detail with entity pool stats and competition list.


        Public — anyone can view a domain''s leaderboard and competition list.

        This enables shareable domain URLs on social media.'
      operationId: get_domain_api_v1_domains__domain_id__get
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
          title: Domain Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Domains
      summary: Update Domain
      description: Update domain settings. Only whitelisted fields are patchable.
      operationId: update_domain_api_v1_domains__domain_id__put
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
          title: Domain Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDomainRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Domains
      summary: Delete Domain
      description: Delete a domain and all its entities. Competitions (rankings) are preserved but unlinked.
      operationId: delete_domain_api_v1_domains__domain_id__delete
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
          title: Domain Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/domains/{domain_id}/exclusivity:
    post:
      tags:
      - Domains
      summary: Set Domain Exclusivity
      description: 'Set or clear an anchor-buyer exclusivity window on a domain.


        Owner only. While `exclusive_until` is in the future, the domain is

        gated from the public L2 marketplace surface (per LOI §1.4 in

        docs/raise/12_anchor_buyer_loi.md).


        To clear: send `{"exclusive_until": null, "exclusive_buyer_label": null}`.'
      operationId: set_domain_exclusivity_api_v1_domains__domain_id__exclusivity_post
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
          title: Domain Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetExclusivityRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/domains/{domain_id}/logo:
    post:
      tags:
      - Domains
      summary: Upload Domain Logo
      description: 'Upload a logo for a domain.


        Mirrors the ranking-thumbnail upload pattern. Saves to

        static/domain-logos/{domain_id}.{ext} via the storage backend

        (S3 in prod, local FS in dev) and sets domain.image_url.

        Returned URL works immediately on the domain detail page.


        Owner-only — checked via the owner_id filter rather than the

        full ranking-permission system because Domains don''t have

        collaborators yet.'
      operationId: upload_domain_logo_api_v1_domains__domain_id__logo_post
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
          title: Domain Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_domain_logo_api_v1_domains__domain_id__logo_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/domains/{domain_id}/entities:
    post:
      tags:
      - Domains
      summary: Add Entities To Domain
      description: Add entities to the domain's entity pool.
      operationId: add_entities_to_domain_api_v1_domains__domain_id__entities_post
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
          title: Domain Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddEntitiesRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Domains
      summary: List Domain Entities
      description: List all entities in a domain's pool, sorted by rating. Public endpoint.
      operationId: list_domain_entities_api_v1_domains__domain_id__entities_get
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
          title: Domain Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/domains/{domain_id}/competitions:
    post:
      tags:
      - Domains
      summary: Create Competition
      description: 'Create a competition (ranking) from the domain''s entity pool.


        In ''open'' mode: creates a ranking linked to the domain. Entities are

        shared — votes update domain-level ratings.


        In ''bracket'' mode: creates a ranking + seeds a bracket tournament

        from the domain''s entity pool.'
      operationId: create_competition_api_v1_domains__domain_id__competitions_post
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
          title: Domain Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api__routes__domains__CreateCompetitionRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Domains
      summary: List Competitions
      description: List all competitions in a domain.
      operationId: list_competitions_api_v1_domains__domain_id__competitions_get
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
          title: Domain Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/domains/{domain_id}/expert-leaderboard:
    get:
      tags:
      - Domains
      summary: Get Expert Leaderboard
      description: 'Top voters in a domain, ranked by Cohen κ vs majority consensus.


        Public — surfaces verified domain expertise as a citable credential.

        Per the L4 expert-influencer strategy: Twitter/Substack experts have

        follower-count authority but no verifiable judgment quality;

        consensus κ converts that into a falsifiable signal.


        Aggregates votes across all competitions (Rankings) under this Domain.

        Voters with fewer than `min_pairs` overlapping pairs are excluded —

        too little signal to estimate κ stably (Layer 4 of the methodology

        paper §4).'
      operationId: get_expert_leaderboard_api_v1_domains__domain_id__expert_leaderboard_get
      parameters:
      - name: domain_id
        in: path
        required: true
        schema:
          type: string
          title: Domain Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
          title: Limit
      - name: min_pairs
        in: query
        required: false
        schema:
          type: integer
          default: 5
          title: Min Pairs
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreateDomainRequest:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 2
          title: Name
        description:
          anyOf:
          - type: string
            maxLength: 4000
          - type: 'null'
          title: Description
        category:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Category
        image_url:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Image Url
        media_type:
          type: string
          pattern: ^(text|image|audio|video)$
          title: Media Type
          default: text
        default_algorithm:
          type: string
          maxLength: 32
          title: Default Algorithm
          default: glicko2
        default_settings:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Default Settings
        visibility:
          type: string
          pattern: ^(public|unlisted|private)$
          title: Visibility
          default: public
        entities:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 500
          - type: 'null'
          title: Entities
        constitution:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Constitution
          description: Optional list of explicit principles voters apply when judging. List of strings or {id,text,category} dicts. Inherited by competitions in this domain.
        objectives:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Objectives
          description: Optional list of evaluation axes — list of strings or {id,name,description,scale} dicts. Declarative; per-axis voting is v2.
      type: object
      required:
      - name
      title: CreateDomainRequest
    AddEntitiesRequest:
      properties:
        entities:
          items:
            additionalProperties: true
            type: object
          type: array
          maxItems: 500
          minItems: 1
          title: Entities
          description: '[{"name": "...", "description": "...", "image_url": "..."}]'
      type: object
      required:
      - entities
      title: AddEntitiesRequest
    api__routes__domains__CreateCompetitionRequest:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 2
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        mode:
          type: string
          pattern: ^(open|bracket)$
          title: Mode
          default: open
        bracket_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bracket Size
          description: Power of 2 for bracket mode
        bracket_strategy:
          type: string
          pattern: ^(rating|random)$
          title: Bracket Strategy
          default: rating
      type: object
      required:
      - name
      title: CreateCompetitionRequest
    Body_upload_domain_logo_api_v1_domains__domain_id__logo_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
          description: Logo image (JPEG/PNG/WebP/GIF, max 2MB)
      type: object
      required:
      - file
      title: Body_upload_domain_logo_api_v1_domains__domain_id__logo_post
    SetExclusivityRequest:
      properties:
        exclusive_until:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Exclusive Until
        exclusive_buyer_label:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Exclusive Buyer Label
      type: object
      title: SetExclusivityRequest
    UpdateDomainRequest:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 255
            minLength: 2
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
            maxLength: 4000
          - type: 'null'
          title: Description
        category:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Category
        image_url:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Image Url
        media_type:
          anyOf:
          - type: string
            pattern: ^(text|image|audio|video)$
          - type: 'null'
          title: Media Type
        default_algorithm:
          anyOf:
          - type: string
            maxLength: 32
          - type: 'null'
          title: Default Algorithm
        default_settings:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Default Settings
        visibility:
          anyOf:
          - type: string
            pattern: ^(public|unlisted|private)$
          - type: 'null'
          title: Visibility
        constitution:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Constitution
        objectives:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Objectives
      type: object
      title: UpdateDomainRequest
      description: 'Whitelisted fields the owner can patch. Prevents mass-assignment

        attacks on owner_id, entity_count, created_at, etc.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key