openapi: 3.1.0
info:
  title: Vibelo Name Scorer API
  description: |
    Analyze any business name with AI-powered linguistic scoring. Get insights on sound symbolism, memorability, distinctiveness, and an overall score from 0-100.

    This is the API behind Vibelo's free name scorer (https://vibelo.ai/free-name-scorer). The full 25-name generation pipeline is only available through the web app at https://vibelo.ai. Every error response is a JSON object with `error`, `code` and `hint` fields.
  version: 1.1.0
  contact:
    name: Vibelo
    email: hello@vibelo.ai
    url: https://vibelo.ai/contact
servers:
  - url: https://vibelo.ai
security:
  - apiKey: []
paths:
  /api/score-name:
    post:
      operationId: scoreName
      summary: Score a business name
      description: |
        Analyzes a business name using AI linguistic models. Returns a detailed breakdown of sound balance, memorability, distinctiveness, and an overall score from 0-100. Optionally provide business context for more relevant analysis.

        Requests from a browser must include a Cloudflare Turnstile token as `turnstileToken`. Other clients authenticate with a bearer API key (see `apiKey`). Rate limit: 10 scores per hour per IP address.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 50
                  description: The business name to analyze
                context:
                  type: string
                  maxLength: 500
                  description: Optional business context (e.g. "A sustainable fashion brand for Gen Z")
                turnstileToken:
                  type: string
                  description: Cloudflare Turnstile token. Required for browser clients that don't send an API key.
      responses:
        "200":
          description: Successful analysis
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique score ID (can be used to share results)
                  name:
                    type: string
                    description: The analyzed business name
                  score:
                    type: integer
                    minimum: 0
                    maximum: 100
                    description: Overall linguistic score
                  soundBalance:
                    type: string
                    description: Analysis of consonant/vowel balance
                  boubaKikiAlignment:
                    type: string
                    enum: [bouba, kiki, balanced]
                    description: "Sound symbolism: bouba (soft/round), kiki (sharp/angular), or balanced"
                  processingFluency:
                    type: string
                    enum: [high, medium, low]
                    description: How easy the name is to process and remember
                  compoundEffect:
                    type: string
                    nullable: true
                    description: Semantic blend effect if the name is a compound word
                  distinctiveness:
                    type: string
                    enum: [high, medium, low]
                    description: How unique/distinctive the name sounds
                  length:
                    type: integer
                    description: Character count
                  syllables:
                    type: integer
                    description: Syllable count
        "400":
          description: Invalid input (`code` is `invalid_json` or `invalid_input`)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Verification failed or missing (`code` is `verification_failed` or `verification_required`)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded, 10 scores per hour per IP (`code` is `rate_limited`)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Scoring failed, safe to retry (`code` is `scoring_failed`)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: API key for integrations. Keys are currently issued only to Vibelo's own integrations; email hello@vibelo.ai to ask about access.
  schemas:
    Error:
      type: object
      required: [error, code, hint]
      properties:
        error:
          type: string
          description: Human-readable message
        code:
          type: string
          description: Stable machine-readable error code
          enum:
            - invalid_json
            - invalid_input
            - verification_failed
            - verification_required
            - rate_limited
            - scoring_failed
            - method_not_allowed
            - not_found
        hint:
          type: string
          description: How to resolve the error
        details:
          type: array
          description: Field-level validation issues (only for `invalid_input`)
          items:
            type: object