Bro Find AI Badge API

openapi: 3.2.0
info:
  title: Bro Find AI Badge API
  description: API for the Bro Find AI AI tools directory. Submit tools, leave reviews and comments, and send feedback.
  version: 1.0.0
  contact:
    name: Bro Find AI Support
    url: https://brofindai.com/support
  license:
    name: Proprietary
    url: https://brofindai.com
servers:
- url: https://brofindai.com
  description: Production
tags:
- name: Badge
paths:
  /api/badge/{toolId}/votes.json:
    get:
      summary: Live upvote count for one listing
      description: 'Public, CORS-open and cacheable for five minutes. The count is merged across every key the listing''s votes are filed under, so it matches the number shown on the listing page. Read by third-party badge embeds, including Make Taksh''s, which get pasted into pages this project does not control: adding keys is safe, renaming one is not.'
      operationId: getBadgeVotes
      parameters:
      - name: toolId
        in: path
        required: true
        description: The listing's slug, or its submission uuid.
        schema:
          type: string
          maxLength: 128
      responses:
        '200':
          description: The listing and its live count.
          content:
            application/json:
              schema:
                type: object
                required:
                - toolId
                - name
                - votes
                - updatedAt
                properties:
                  toolId:
                    type: string
                    description: The listing's slug.
                  name:
                    type: string
                  votes:
                    type: integer
                    minimum: 0
                  url:
                    type: string
                    format: uri
                    description: The listing page.
                  updatedAt:
                    type: string
                    format: date-time
                    description: When the count was read, not when it last changed.
                  makeTakshUsername:
                    type:
                    - string
                    - 'null'
                    description: The owner's Make Taksh handle, if they linked one.
        '404':
          description: No approved listing has that id.
      tags:
      - Badge
  /api/badge/votes.json:
    get:
      summary: Live upvote counts for every listing owned by one Make Taksh maker
      description: Returns a bare JSON array, not an envelope. The URL and the array shape both come from Make Taksh's client (src/lib/brofind.ts in their repo), which is written against this exact form.
      operationId: getBadgeVotesByMaker
      parameters:
      - name: makeTakshUsername
        in: query
        required: true
        description: 'A Make Taksh handle: lowercase letters, digits and hyphens.'
        schema:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9-]{1,26}[a-z0-9])?$
      responses:
        '200':
          description: 'The maker''s approved listings, most upvoted first. Empty when the handle is unclaimed or unusable: an unknown handle is not an error.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/paths/~1api~1badge~1%7BtoolId%7D~1votes.json/get/responses/200/content/application~1json/schema'
        '400':
          description: makeTakshUsername was not supplied.
      tags:
      - Badge
  /api/badge/{toolId}.svg:
    get:
      summary: The upvote badge as an SVG image
      description: For READMEs and anywhere a maker can drop an but not a . Carries its own copy of Figtree as an embedded subset, because an -embedded SVG loads no external resource. Colours are fixed brand colours and are not a parameter. Shader backgrounds are unavailable here (a static image runs no JavaScript) and degrade to the flat themed card.
      operationId: getBadgeSvg
      parameters:
      - name: toolId
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
      - name: theme
        in: query
        required: false
        description: auto follows the viewer's prefers-color-scheme.
        schema:
          type: string
          enum:
          - auto
          - light
          - dark
          default: light
      - name: size
        in: query
        required: false
        schema:
          type: string
          enum:
          - compact
          - standard
          - large
          default: standard
      responses:
        '200':
          description: The badge.
          content:
            image/svg+xml:
              schema:
                type: string
        '404':
          description: No approved listing has that id. A badge is still rendered.
      tags:
      - Badge
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Firebase ID Token
      description: Firebase Authentication ID token obtained via Google Sign-In