Bynn Intelligence Face Collections API

openapi: 3.2.0
info:
  title: BYNN Face Collections 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 Collections
  description: Operations about Face Collections
paths:
  /face-collections:
    post:
      summary: Create a face collection
      description: Create a new face collection for your organization. Collections are used to group enrolled faces for search and identification.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postFaceCollections'
        required: true
      security:
      - PrivateKey: []
      responses:
        '201':
          description: Create a face collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_FaceCollectionEntity'
        '401':
          description: Unauthorized - Invalid or missing API key
        '422':
          description: Validation error - Missing required parameters
        '429':
          description: Rate limit exceeded
      tags:
      - Face Collections
      operationId: postFaceCollections
    get:
      summary: List face collections
      description: List all face collections belonging to your organization, ordered by most recently created. Each collection includes the number of enrolled faces. Supports pagination via page and per_page parameters.
      parameters:
      - in: query
        name: page
        description: Page number (1-based)
        required: false
        example: 1
        schema:
          type: integer
          format: int32
          default: 1
      - in: query
        name: per_page
        description: Number of collections per page (1-100)
        required: false
        example: 25
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 100
          default: 25
      security:
      - PrivateKey: []
      responses:
        '200':
          description: List face collections
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bynn_V1_Entities_FaceCollectionEntity'
        '401':
          description: Unauthorized - Invalid or missing API key
        '429':
          description: Rate limit exceeded
      tags:
      - Face Collections
      operationId: getFaceCollections
  /face-collections/{token}:
    delete:
      summary: Delete a face collection
      description: Delete a face collection and all its enrolled faces. This action is irreversible.
      parameters:
      - in: path
        name: token
        description: Collection token (e.g. fc_abc123)
        required: true
        example: fc_abc123def456
        schema:
          type: string
      security:
      - PrivateKey: []
      responses:
        '204':
          description: Delete a face collection
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Collection not found
        '429':
          description: Rate limit exceeded
      tags:
      - Face Collections
      operationId: deleteFaceCollectionsToken
components:
  schemas:
    postFaceCollections:
      type: object
      properties:
        name:
          type: string
          description: Name for the face collection (max 255 characters)
          example: Employee Faces
        description:
          type: string
          description: Optional description of the collection (max 1000 characters)
          example: Headshots for building access control
      required:
      - name
      description: Create a face collection
    Bynn_V1_Entities_FaceCollectionEntity:
      type: object
      properties:
        collection_id:
          type: string
          example: fc_abc123def456
          description: Unique collection identifier with fc_ prefix
        name:
          type: string
          example: Employee Faces
          description: Name of the face collection
        description:
          type: string
          example: Collection of employee headshots for access control
          description: Optional description of the collection
        face_count:
          type: integer
          format: int32
          example: 42
          description: Number of enrolled faces in the collection
        created_at:
          type: string
          example: '2024-01-15T10:30:00Z'
          description: When the collection was created (ISO 8601)
      required:
      - collection_id
      - name
      - description
      - face_count
      - created_at
      description: Bynn_V1_Entities_FaceCollectionEntity 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`