Bynn Intelligence Face Search API

openapi: 3.2.0
info:
  title: BYNN Face Search API
  description: 'The BYNN API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects. To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test-mode credentials never hit live networks and incur no cost. **AUTHENTICATION:** Use your **Private API Key**, which looks like `private_xxxxxxxxxxxxxxxxxxxxxxxx` (or `private_sandbox_xxxxxxxxxxxxxxxxxxxxxxxx` for a sandbox key), as the username in HTTP Basic auth with an empty password, or send it as `Authorization: Bearer `. Your keys are at https://dashboard.bynn.com/integration.'
  termsOfService: https://bynn.com/terms
  contact:
    name: BYNN Development Team
    email: hello@bynn.com
    url: https://docs.bynn.com
  license:
    name: BYNN Documentation
    url: https://docs.bynn.com
  version: '1.0'
servers:
- url: https://api.bynn.com/v1
tags:
- name: Face Search
  description: Operations about Face Searches
paths:
  /face-collections/{token}/search:
    post:
      summary: Search for faces in a collection
      description: Search for similar faces in a collection by providing a probe image (URL, base64, or file upload). Returns matching faces ordered by similarity (lowest distance first). If the image contains multiple faces, the largest/first detected face is used for the search.
      parameters:
      - in: path
        name: token
        description: Collection token (e.g. fc_abc123)
        required: true
        example: fc_abc123def456
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postFaceCollectionsTokenSearch'
        required: true
      security:
      - PrivateKey: []
      responses:
        '201':
          description: Search for faces in a collection
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bynn_V1_Entities_FaceSearchResultEntity'
        '400':
          description: No face detected in probe image
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Collection not found
        '422':
          description: Validation error - Invalid input
        '429':
          description: Rate limit exceeded
      tags:
      - Face Search
      operationId: postFaceCollectionsTokenSearch
components:
  schemas:
    postFaceCollectionsTokenSearch:
      type: object
      properties:
        image_url:
          type: string
          description: URL of the image containing a face to search for
          example: https://example.com/photo.jpg
        base64_image:
          type: string
          description: Base64 strict encoded image data (max 20MB decoded)
        file:
          type: string
          format: binary
          description: Image file upload (multipart/form-data, max 20MB)
        limit:
          type: integer
          format: int32
          description: Maximum number of results to return (1-100)
          minimum: 1
          maximum: 100
          default: 10
          example: 10
        distance_threshold:
          type: number
          format: float
          description: Max cosine distance for matches (0.1-1.0, lower is stricter); omit for the gallery-calibrated default.
          example: 0.5
      description: Search for faces in a collection
    Bynn_V1_Entities_FaceSearchResultEntity:
      type: object
      properties:
        face_id:
          type: string
          example: face_abc123def456
          description: Unique face identifier with face_ prefix
        name:
          type: string
          example: John Doe
          description: Name or label of the matched face
        external_id:
          type: string
          example: emp_12345
          description: External reference ID of the matched face
        distance:
          type: number
          example: 0.23
          description: Cosine distance between the query face and this match (lower is more similar)
        similarity:
          type: number
          example: 0.77
          description: Similarity score (1 - distance, higher is more similar)
        metadata:
          type: object
          description: Additional metadata associated with the face
      required:
      - face_id
      - name
      - external_id
      - distance
      - similarity
      - metadata
      description: Bynn_V1_Entities_FaceSearchResultEntity model
  securitySchemes:
    PrivateKey:
      type: apiKey
      name: Authorization
      in: header
      description: Enter your PRIVATE KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`
    PublicKey:
      type: apiKey
      name: Authorization
      in: header
      description: Enter your PUBLIC KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`