AimRank Users API

openapi: 3.2.0
info:
  title: AimRank Users 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: Users
paths:
  /api/v1/users/me:
    get:
      tags:
      - Users
      summary: Get Profile
      description: Get current user's full profile.
      operationId: get_profile_api_v1_users_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api__routes__users__UserProfileResponse'
    put:
      tags:
      - Users
      summary: Update Profile
      description: Update current user's profile.
      operationId: update_profile_api_v1_users_me_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserProfileUpdate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api__routes__users__UserProfileResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Users
      summary: Delete Account
      description: Delete current user's account (soft delete — anonymize PII).
      operationId: delete_account_api_v1_users_me_delete
      responses:
        '204':
          description: Successful Response
  /api/v1/users/me/data-export:
    get:
      tags:
      - Users
      summary: Export My Data
      description: 'Export all personal data (GDPR Article 20 — Right to Data Portability).


        Returned synchronously: a single user''s export is a handful of indexed

        queries. The previous background-job path returned only a ``{job_id}`` stub

        that the frontend downloaded *as* the user''s data (it never polled), so in

        any environment with Redis/ARQ (i.e. production) the export delivered no

        data. Returning the payload directly is both correct and simpler.'
      operationId: export_my_data_api_v1_users_me_data_export_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/v1/users/me/password:
    post:
      tags:
      - Users
      summary: Change Password
      description: 'Change current user''s password.


        Every session issued before the change is refused from now on (a stolen

        token must not outlive the change); this device gets a fresh pair so the

        person who changed it stays signed in.'
      operationId: change_password_api_v1_users_me_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordChange'
        required: true
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/users/me/delete-request:
    post:
      tags:
      - Users
      summary: Request Account Deletion
      description: Request account deletion (GDPR Article 17 — Right to Erasure).
      operationId: request_account_deletion_api_v1_users_me_delete_request_post
      parameters:
      - name: hard_delete
        in: query
        required: false
        schema:
          type: boolean
          description: Permanently delete all data
          default: false
          title: Hard Delete
        description: Permanently delete all data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteAccountRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/users/{user_id}:
    get:
      tags:
      - Users
      summary: Get Public Profile
      description: Get a user's public profile.
      operationId: get_public_profile_api_v1_users__user_id__get
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/users/{user_id}/expertise:
    get:
      tags:
      - Users
      summary: Get User Expertise
      description: 'The user''s per-domain Cohen κ scores — their portable credential.


        Public. Per the L4 expert-influencer strategy: this is what an

        influencer links from their Twitter bio / Substack header

        ("verified by AimRank · domain X · κ=0.78"). Each domain''s κ is

        computed against majority consensus across all competitions in

        that domain — Layer 4 of the methodology paper §4.


        Domains where the user has fewer than `min_pairs` overlapping pairs

        are excluded — too little signal to estimate κ stably.'
      operationId: get_user_expertise_api_v1_users__user_id__expertise_get
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - 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
    DeleteAccountRequest:
      properties:
        password:
          type: string
          title: Password
        confirm_text:
          type: string
          title: Confirm Text
          description: Must be 'DELETE'
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
      type: object
      required:
      - password
      - confirm_text
      title: DeleteAccountRequest
    api__routes__users__UserProfileResponse:
      properties:
        id:
          type: string
          title: Id
        email:
          type: string
          title: Email
        name:
          type: string
          title: Name
        bio:
          anyOf:
          - type: string
          - type: 'null'
          title: Bio
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
        expertise_areas:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Expertise Areas
        professional_links:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Professional Links
        industry:
          anyOf:
          - type: string
          - type: 'null'
          title: Industry
        job_role:
          anyOf:
          - type: string
          - type: 'null'
          title: Job Role
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
        languages:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Languages
        paid_voting_optin:
          type: boolean
          title: Paid Voting Optin
          default: false
        expertise_verified:
          type: boolean
          title: Expertise Verified
          default: false
        created_at:
          type: string
          format: date-time
          title: Created At
        stats:
          additionalProperties: true
          type: object
          title: Stats
      type: object
      required:
      - id
      - email
      - name
      - created_at
      - stats
      title: UserProfileResponse
    UserProfileUpdate:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        bio:
          anyOf:
          - type: string
          - type: 'null'
          title: Bio
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
        expertise_areas:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 20
          - type: 'null'
          title: Expertise Areas
          description: Voluntary expertise tags, e.g. ["code review", "TTS prosody"]
        professional_links:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Professional Links
          description: Voluntary {linkedin, github, website} URLs
        industry:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Industry
        job_role:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Job Role
        country:
          anyOf:
          - type: string
            maxLength: 2
            minLength: 2
          - type: 'null'
          title: Country
          description: ISO 3166-1 alpha-2 country code (e.g. 'LT', 'DE')
        languages:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 10
          - type: 'null'
          title: Languages
          description: ISO 639-1 language codes
        paid_voting_optin:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Paid Voting Optin
          description: Opt-in to be considered for future paid recruitment in domains matching your declared profile (L4 marketplace)
      type: object
      title: UserProfileUpdate
    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
    PasswordChange:
      properties:
        current_password:
          type: string
          title: Current Password
        new_password:
          type: string
          minLength: 10
          title: New Password
      type: object
      required:
      - current_password
      - new_password
      title: PasswordChange
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key