AimRank Entities API

openapi: 3.2.0
info:
  title: AimRank Entities 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: Entities
paths:
  /api/v1/entities:
    post:
      tags:
      - Entities
      summary: Create Entity
      description: Add an entity to a ranking.
      operationId: create_entity_api_v1_entities_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/entities/bulk:
    post:
      tags:
      - Entities
      summary: Create Entities Bulk
      description: Bulk add entities to a ranking.
      operationId: create_entities_bulk_api_v1_entities_bulk_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityBulkCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/entities/import-csv:
    post:
      tags:
      - Entities
      summary: Import Csv
      description: 'Import entities from a CSV file.


        Expected CSV columns:

        - ``name`` (required) — entity name

        - ``description`` (optional) — entity description

        - ``image_url`` (optional) — image URL

        - ``attributes`` (optional) — JSON string of custom attributes


        Max 500 entities per import. File must be < 1 MB.'
      operationId: import_csv_api_v1_entities_import_csv_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_import_csv_api_v1_entities_import_csv_post'
        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/entities/bulk-media:
    post:
      tags:
      - Entities
      summary: Bulk Upload Media
      description: 'Bulk-create entities + their media in one upload.


        Designed for the AI-lab use case: a creator drops 50 generated videos

        that all share `{model: ''Veo3'', prompt: ''...''}` and just wants random

        IDs assigned. Replaces the alternative of 50 round-trips of

        POST /entities + POST /entities/{id}/media.


        Limits:

        - Up to 50 files per call (sync). Larger batches should chunk client-side.

        - Total batch ≤ 1 GB (declared via Content-Length).

        - All files must match the ranking''s media_type. Mixed batches rejected.

        - Per-file size still bounded by MEDIA_LIMITS (2 MB image, 10 MB audio, 200 MB video).


        On per-file processing failure, the entity for that file is rolled back

        and the error is returned in the response so the client can retry just

        the failed ones — partial success is normal and expected for big batches.'
      operationId: bulk_upload_media_api_v1_entities_bulk_media_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_bulk_upload_media_api_v1_entities_bulk_media_post'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/entities/{entity_id}/media:
    post:
      tags:
      - Entities
      summary: Upload Entity Media
      description: 'Upload media for an entity — image, audio, or video.


        The ranking''s media_type determines what''s accepted.

        - Image: JPEG/PNG/WebP/GIF → center-cropped 400x400 JPEG

        - Audio: MP3/WAV/OGG/M4A → saved as-is with waveform thumbnail (max 60s)

        - Video: MP4/WebM/MOV → saved as-is with frame thumbnail (max 15s)


        Returns media_url + thumbnail + metadata.'
      operationId: upload_entity_media_api_v1_entities__entity_id__media_post
      parameters:
      - name: entity_id
        in: path
        required: true
        schema:
          type: string
          title: Entity Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_entity_media_api_v1_entities__entity_id__media_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/entities/{entity_id}:
    get:
      tags:
      - Entities
      summary: Get Entity
      description: Get entity details.
      operationId: get_entity_api_v1_entities__entity_id__get
      parameters:
      - name: entity_id
        in: path
        required: true
        schema:
          type: string
          title: Entity Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Entities
      summary: Update Entity
      description: Update an entity.
      operationId: update_entity_api_v1_entities__entity_id__put
      security:
      - APIKeyHeader: []
      parameters:
      - name: entity_id
        in: path
        required: true
        schema:
          type: string
          title: Entity Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Entities
      summary: Delete Entity
      description: Delete an entity (soft delete).
      operationId: delete_entity_api_v1_entities__entity_id__delete
      parameters:
      - name: entity_id
        in: path
        required: true
        schema:
          type: string
          title: Entity Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/entities/ranking/{ranking_id}:
    get:
      tags:
      - Entities
      summary: List Entities By Ranking
      description: List all entities in a ranking (paginated).
      operationId: list_entities_by_ranking_api_v1_entities_ranking__ranking_id__get
      parameters:
      - name: ranking_id
        in: path
        required: true
        schema:
          type: string
          title: Ranking Id
      - name: sort_by
        in: query
        required: false
        schema:
          enum:
          - rating
          - name
          - matches
          type: string
          default: rating
          title: Sort By
      - name: order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          default: desc
          title: Order
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          description: Items per page (max 500)
          default: 100
          title: Page Size
        description: Items per page (max 500)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/entities/{entity_id}/history:
    get:
      tags:
      - Entities
      summary: Get Entity History
      description: 'Get rating history for an entity.


        - **time_range**: How far back to look (1m, 3m, 6m, 1y, all)

        - **resolution**: Granularity of data (raw, daily, weekly)


        Returns time-series data for charting.'
      operationId: get_entity_history_api_v1_entities__entity_id__history_get
      parameters:
      - name: entity_id
        in: path
        required: true
        schema:
          type: string
          title: Entity Id
      - name: time_range
        in: query
        required: false
        schema:
          enum:
          - 1m
          - 3m
          - 6m
          - 1y
          - all
          type: string
          default: 6m
          title: Time Range
      - name: resolution
        in: query
        required: false
        schema:
          enum:
          - raw
          - daily
          - weekly
          type: string
          default: daily
          title: Resolution
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityHistoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/entities/suggest/{ranking_id}:
    post:
      tags:
      - Entities
      summary: Suggest Entity
      description: 'Suggest an entity to be added to a ranking.


        Anyone can suggest (logged in or not). Owner gets a notification.

        Suggestions are stored as inactive entities with a ''suggested'' source tag.'
      operationId: suggest_entity_api_v1_entities_suggest__ranking_id__post
      parameters:
      - name: ranking_id
        in: path
        required: true
        schema:
          type: string
          title: Ranking Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitySuggestion'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/entities/pending/{ranking_id}:
    get:
      tags:
      - Entities
      summary: List Pending Suggestions
      description: 'List entities awaiting owner approval for this ranking.


        Owner-only. Returns each suggestion''s display fields so the moderation

        UI can render the same shape it would render on the leaderboard if it

        were approved, plus the `_suggested_by` marker for audit.'
      operationId: list_pending_suggestions_api_v1_entities_pending__ranking_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: ranking_id
        in: path
        required: true
        schema:
          type: string
          title: Ranking Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/entities/{entity_id}/approve:
    post:
      tags:
      - Entities
      summary: Approve Suggestion
      description: 'Approve a suggested entity — flips is_active=True and strips the

        `_suggested*` moderation markers so the entity becomes indistinguishable

        from owner-created ones in queries + exports.'
      operationId: approve_suggestion_api_v1_entities__entity_id__approve_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: entity_id
        in: path
        required: true
        schema:
          type: string
          title: Entity Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/entities/{entity_id}/reject:
    post:
      tags:
      - Entities
      summary: Reject Suggestion
      description: 'Reject a suggested entity — hard-deletes it. Pre-PoC scope: no audit

        trail, no rejection-reason capture. Owner can re-suggest themselves if

        they change their mind.'
      operationId: reject_suggestion_api_v1_entities__entity_id__reject_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: entity_id
        in: path
        required: true
        schema:
          type: string
          title: Entity Id
      responses:
        '204':
          description: Successful Response
        '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
    EntityDetailResponse:
      properties:
        id:
          type: string
          title: Id
        ranking_id:
          type: string
          title: Ranking Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Image Url
        attributes:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Attributes
        mu:
          type: number
          title: Mu
        phi:
          type: number
          title: Phi
        sigma:
          type: number
          title: Sigma
        match_count:
          type: integer
          title: Match Count
        win_count:
          type: integer
          title: Win Count
        created_at:
          type: string
          format: date-time
          title: Created At
        rank:
          type: integer
          title: Rank
        loss_count:
          type: integer
          title: Loss Count
        draw_count:
          type: integer
          title: Draw Count
        win_rate:
          type: number
          title: Win Rate
        win_probability_vs_top:
          anyOf:
          - type: number
          - type: 'null'
          title: Win Probability Vs Top
        recent_matches:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Recent Matches
      type: object
      required:
      - id
      - ranking_id
      - name
      - description
      - image_url
      - attributes
      - mu
      - phi
      - sigma
      - match_count
      - win_count
      - created_at
      - rank
      - loss_count
      - draw_count
      - win_rate
      - win_probability_vs_top
      - recent_matches
      title: EntityDetailResponse
    EntityCreate:
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
          description: Entity name
        ranking_id:
          type: string
          maxLength: 36
          minLength: 36
          title: Ranking Id
          description: UUID of the ranking
        description:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Description
          description: Entity description
        image_url:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Image Url
          description: Image URL
        attributes:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Attributes
          description: Custom attributes (max 50 keys)
      type: object
      required:
      - name
      - ranking_id
      title: EntityCreate
      description: Create a new entity within a ranking.
    EntitySuggestion:
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
        description:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Description
        image_url:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
          title: Image Url
        attributes:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Attributes
      type: object
      required:
      - name
      title: EntitySuggestion
      description: 'Mirrors the canonical entity-create form (name + description + image_url

        + attributes) so a suggestion arrives with enough metadata that the owner

        can approve it without filling in the gaps. The owner moderation gate is

        enforced via Entity.is_active=False — suggestions stay invisible to vote

        + leaderboard queries until /approve flips them.'
    Body_upload_entity_media_api_v1_entities__entity_id__media_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
          description: 'Media file: image (2MB), audio (10MB/60s), or video (200MB/60s)'
      type: object
      required:
      - file
      title: Body_upload_entity_media_api_v1_entities__entity_id__media_post
    Body_import_csv_api_v1_entities_import_csv_post:
      properties:
        ranking_id:
          type: string
          title: Ranking Id
          description: UUID of the ranking to import into
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
          description: CSV file with entity data
      type: object
      required:
      - ranking_id
      - file
      title: Body_import_csv_api_v1_entities_import_csv_post
    HistorySummary:
      properties:
        start_rating:
          type: number
          title: Start Rating
        current_rating:
          type: number
          title: Current Rating
        peak_rating:
          type: number
          title: Peak Rating
        peak_date:
          type: string
          title: Peak Date
        lowest_rating:
          type: number
          title: Lowest Rating
        total_changes:
          type: integer
          title: Total Changes
        wins:
          type: integer
          title: Wins
        losses:
          type: integer
          title: Losses
        draws:
          type: integer
          title: Draws
      type: object
      required:
      - start_rating
      - current_rating
      - peak_rating
      - peak_date
      - lowest_rating
      - total_changes
      - wins
      - losses
      - draws
      title: HistorySummary
    EntityUpdate:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 200
            minLength: 1
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Image Url
        attributes:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Attributes
      type: object
      title: EntityUpdate
    EntityHistoryResponse:
      properties:
        entity_id:
          type: string
          title: Entity Id
        entity_name:
          type: string
          title: Entity Name
        ranking_id:
          type: string
          title: Ranking Id
        time_range:
          type: string
          title: Time Range
        resolution:
          type: string
          title: Resolution
        data:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Data
        summary:
          $ref: '#/components/schemas/HistorySummary'
      type: object
      required:
      - entity_id
      - entity_name
      - ranking_id
      - time_range
      - resolution
      - data
      - summary
      title: EntityHistoryResponse
    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
    EntityResponse:
      properties:
        id:
          type: string
          title: Id
        ranking_id:
          type: string
          title: Ranking Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Image Url
        attributes:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Attributes
        mu:
          type: number
          title: Mu
        phi:
          type: number
          title: Phi
        sigma:
          type: number
          title: Sigma
        match_count:
          type: integer
          title: Match Count
        win_count:
          type: integer
          title: Win Count
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - ranking_id
      - name
      - description
      - image_url
      - attributes
      - mu
      - phi
      - sigma
      - match_count
      - win_count
      - created_at
      title: EntityResponse
    EntityBulkCreate:
      properties:
        ranking_id:
          type: string
          maxLength: 36
          minLength: 36
          title: Ranking Id
          description: UUID of the ranking
        entities:
          items:
            additionalProperties: true
            type: object
          type: array
          maxItems: 100
          minItems: 1
          title: Entities
          description: List of entities
      type: object
      required:
      - ranking_id
      - entities
      title: EntityBulkCreate
      description: Bulk create multiple entities within a ranking.
    Body_bulk_upload_media_api_v1_entities_bulk_media_post:
      properties:
        ranking_id:
          type: string
          title: Ranking Id
          description: UUID of the ranking to upload into
        files:
          items:
            type: string
            contentMediaType: application/octet-stream
          type: array
          title: Files
          description: Media files (image/audio/video, all same media_type as the ranking)
        shared_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Shared Description
          description: Description applied to every entity
        shared_attributes:
          anyOf:
          - type: string
          - type: 'null'
          title: Shared Attributes
          description: JSON object of shared attributes (model, prompt, params, etc.)
        sweep_metadata:
          anyOf:
          - type: string
          - type: 'null'
          title: Sweep Metadata
          description: JSON array of {name, value, range?} describing the sweep that produced this batch — persisted on ranking.settings.sweep
        name_from_filename:
          type: boolean
          title: Name From Filename
          description: Use filename (without extension) as entity name; otherwise auto-generate
          default: true
      type: object
      required:
      - ranking_id
      - files
      title: Body_bulk_upload_media_api_v1_entities_bulk_media_post
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key