Bynn Intelligence Face Enrollment API

openapi: 3.2.0
info:
  title: BYNN Face Enrollment 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 Enrollment
  description: Operations about Face Enrollments
paths:
  /face-collections/{token}/enroll:
    post:
      summary: Enroll a face into a collection
      description: Enroll a single face into a collection by providing an image URL, base64-encoded image, or a file upload (multipart/form-data). The image must contain exactly one face. If no face or multiple faces are detected, an error is returned. You can optionally provide a name, external_id, and metadata for the enrolled face.
      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/postFaceCollectionsTokenEnroll'
        required: true
      security:
      - PrivateKey: []
      responses:
        '201':
          description: Enroll a face into a collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_FaceEntity'
        '400':
          description: No face detected or multiple faces detected in 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 Enrollment
      operationId: postFaceCollectionsTokenEnroll
  /face-collections/{collection_token}/faces/{face_token}:
    delete:
      summary: Delete a face from a collection
      description: Remove an enrolled face from a collection. This action is irreversible and the face embedding will be permanently deleted.
      parameters:
      - in: path
        name: collection_token
        description: Collection token (e.g. fc_abc123)
        required: true
        example: fc_abc123def456
        schema:
          type: string
      - in: path
        name: face_token
        description: Face token (e.g. face_abc123)
        required: true
        example: face_abc123def456
        schema:
          type: string
      security:
      - PrivateKey: []
      responses:
        '204':
          description: Delete a face from a collection
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Collection or face not found
        '429':
          description: Rate limit exceeded
      tags:
      - Face Enrollment
      operationId: deleteFaceCollectionsCollectionTokenFacesFaceToken
components:
  schemas:
    Bynn_V1_Entities_FaceEntity:
      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 for the enrolled face
        external_id:
          type: string
          example: emp_12345
          description: External reference ID for integration with your system
        category:
          type: string
          example: celeb_sport
          description: Face category (celeb_sport, celeb_movie, celeb_other, unknown)
        metadata:
          type: object
          example:
            department: Engineering
          description: Additional metadata associated with the face
        created_at:
          type: string
          example: '2024-01-15T10:30:00Z'
          description: When the face was enrolled (ISO 8601)
      required:
      - face_id
      - name
      - external_id
      - category
      - metadata
      - created_at
      description: Bynn_V1_Entities_FaceEntity model
    postFaceCollectionsTokenEnroll:
      type: object
      properties:
        image_url:
          type: string
          description: URL of the image containing a face
          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)
        name:
          type: string
          description: Name or label for the enrolled face (max 255 characters)
          example: John Doe
        external_id:
          type: string
          description: External reference ID for your system (max 255 characters)
          example: emp_12345
        metadata:
          type: object
          description: Additional metadata to store with the face (max 16KB)
          example:
            department: Engineering
      description: Enroll a face into a collection
  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`