Amazon Rekognition Rekognition User API

openapi: 3.1.0
info:
  title: Amazon Rekognition User API
  version: '2016-06-27'
  description: Generated from AWS's published Smithy model for Amazon Rekognition. 5 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://rekognition.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /#CreateUser:
    post:
      operationId: CreateUser
      summary: Create User
      description: Creates a new User within a collection specified by CollectionId. Takes UserId as a parameter, which is
        a user provided ID which should be unique within the collection. The provided UserId will alias the system generated
        UUID to make the UserId more user friendly. Uses a ClientToken, an idempotency token that ensures a call to CreateUser
        completes only once. If the value is not supplied, the AWS SDK generates an idempotency token for the requests. This
        prevents retries after a network error results from making multiple CreateUser calls.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/CreateUserResponse'
        '400':
          description: AccessDeniedException; ConflictException; IdempotentParameterMismatchException; InvalidParameterException;
            ProvisionedThroughputExceededException; ResourceNotFoundException; ServiceQuotaExceededException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerError; ThrottlingException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - RekognitionService.CreateUser
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            example:
              CollectionId: MyCollection
              UserId: DemoUser
      tags:
      - User
  /#DeleteUser:
    post:
      operationId: DeleteUser
      summary: Delete User
      description: Deletes the specified UserID within the collection. Faces that are associated with the UserID are disassociated
        from the UserID before deleting the specified UserID. If the specified Collection or UserID is already deleted or
        not found, a ResourceNotFoundException will be thrown. If the action is successful with a 200 response, an empty HTTP
        body is returned.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DeleteUserResponse'
        '400':
          description: AccessDeniedException; ConflictException; IdempotentParameterMismatchException; InvalidParameterException;
            ProvisionedThroughputExceededException; ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerError; ThrottlingException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - RekognitionService.DeleteUser
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeleteUserRequest'
            example:
              CollectionId: MyCollection
              UserId: DemoUser
              ClientRequestToken: 550e8400-e29b-41d4-a716-446655440001
      tags:
      - User
  /#ListUsers:
    post:
      operationId: ListUsers
      summary: List Users
      description: Returns metadata of the User such as UserID in the specified collection. Anonymous User (to reserve faces
        without any identity) is not returned as part of this request. The results are sorted by system generated primary
        key ID. If the response is truncated, NextToken is returned in the response that can be used in the subsequent request
        to retrieve the next set of identities.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListUsersResponse'
              example:
                NextToken: MGYZLAHX1T5a....
                Users:
                - UserId: demoUser4
                  UserStatus: CREATED
                - UserId: demoUser2
                  UserStatus: CREATED
        '400':
          description: AccessDeniedException; InvalidPaginationTokenException; InvalidParameterException; ProvisionedThroughputExceededException;
            ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerError; ThrottlingException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - RekognitionService.ListUsers
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListUsersRequest'
            example:
              CollectionId: MyCollection
      tags:
      - User
  /#SearchUsers:
    post:
      operationId: SearchUsers
      summary: Search Users
      description: Searches for UserIDs within a collection based on a FaceId or UserId. This API can be used to find the
        closest UserID (with a highest similarity) to associate a face. The request must be provided with either FaceId or
        UserId. The operation returns an array of UserID that match the FaceId or UserId, ordered by similarity score with
        the highest similarity first.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/SearchUsersResponse'
              example:
                SearchedUser:
                  UserId: DemoUser
                UserMatches:
                - User:
                    UserId: demoUser1
                    UserStatus: ACTIVE
                  Similarity: 99.88186645507812
                FaceModelVersion: '6'
        '400':
          description: AccessDeniedException; InvalidParameterException; ProvisionedThroughputExceededException; ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerError; ThrottlingException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - RekognitionService.SearchUsers
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/SearchUsersRequest'
            example:
              CollectionId: MyCollection
              UserId: DemoUser
              MaxUsers: 2
              UserMatchThreshold: 70
      tags:
      - User
  /#SearchUsersByImage:
    post:
      operationId: SearchUsersByImage
      summary: Search Users By Image
      description: Searches for UserIDs using a supplied image. It first detects the largest face in the image, and then searches
        a specified collection for matching UserIDs. The operation returns an array of UserIDs that match the face in the
        supplied image, ordered by similarity score with the highest similarity first. It also returns a bounding box for
        the face found in the input image. Information about faces detected in the supplied image, but not used for the search,
        is returned in an array of UnsearchedFace objects. If no valid face is detected in the image, the response will contain
        an empty UserMatches list and no SearchedFace object.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/SearchUsersByImageResponse'
              example:
                SearchedFace:
                  FaceDetail:
                    BoundingBox:
                      Width: 0.03692837432026863
                      Top: 0.5391526818275452
                      Left: 0.3598678708076477
                      Height: 0.07510016113519669
                UserMatches:
                - User:
                    UserId: demoUser1
                    UserStatus: ACTIVE
                  Similarity: 99.88186645507812
                FaceModelVersion: '6'
                UnsearchedFaces:
                - FaceDetails:
                    BoundingBox:
                      Width: 0.031677018851041794
                      Top: 0.5593535900115967
                      Left: 0.6102562546730042
                      Height: 0.0682177022099495
                  Reasons:
                  - FACE_NOT_LARGEST
                - FaceDetails:
                    BoundingBox:
                      Width: 0.03254449740052223
                      Top: 0.6080358028411865
                      Left: 0.516062319278717
                      Height: 0.06347997486591339
                  Reasons:
                  - FACE_NOT_LARGEST
        '400':
          description: AccessDeniedException; ImageTooLargeException; InvalidImageFormatException; InvalidParameterException;
            InvalidS3ObjectException; ProvisionedThroughputExceededException; ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerError; ThrottlingException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - RekognitionService.SearchUsersByImage
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/SearchUsersByImageRequest'
            example:
              CollectionId: MyCollection
              Image:
                S3Object:
                  Bucket: bucket
                  Name: input.jpg
              MaxUsers: 2
              UserMatchThreshold: 70
              QualityFilter: MEDIUM
      tags:
      - User
components:
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical
        request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: rekognition
  schemas:
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
        Logref:
          type: string
          description: A universally unique identifier (UUID) for the request.
    AgeRange:
      type: object
      properties:
        Low:
          type: integer
          description: The lowest estimated age.
        High:
          type: integer
          description: The highest estimated age.
    Beard:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the face has beard or not.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    BoundingBox:
      type: object
      properties:
        Width:
          type: number
          description: Width of the bounding box as a ratio of the overall image width.
        Height:
          type: number
          description: Height of the bounding box as a ratio of the overall image height.
        Left:
          type: number
          description: Left coordinate of the bounding box as a ratio of overall image width.
        Top:
          type: number
          description: Top coordinate of the bounding box as a ratio of overall image height.
    CreateUserRequest:
      type: object
      properties:
        CollectionId:
          type: string
          description: The ID of an existing collection to which the new UserID needs to be created.
        UserId:
          type: string
          description: ID for the UserID to be created. This ID needs to be unique within the collection.
        ClientRequestToken:
          type: string
          description: Idempotent token used to identify the request to CreateUser. If you use the same token with multiple
            CreateUser requests, the same response is returned. Use ClientRequestToken to prevent the same request from being
            processed more than once.
      required:
      - CollectionId
      - UserId
    CreateUserResponse:
      type: object
      properties: {}
    DeleteUserRequest:
      type: object
      properties:
        CollectionId:
          type: string
          description: The ID of an existing collection from which the UserID needs to be deleted.
        UserId:
          type: string
          description: ID for the UserID to be deleted.
        ClientRequestToken:
          type: string
          description: Idempotent token used to identify the request to DeleteUser. If you use the same token with multiple
            DeleteUser requests, the same response is returned. Use ClientRequestToken to prevent the same request from being
            processed more than once.
      required:
      - CollectionId
      - UserId
    DeleteUserResponse:
      type: object
      properties: {}
    Emotion:
      type: object
      properties:
        Type:
          type: string
          enum:
          - HAPPY
          - SAD
          - ANGRY
          - CONFUSED
          - DISGUSTED
          - SURPRISED
          - CALM
          - UNKNOWN
          - FEAR
          description: Type of emotion detected.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    EyeDirection:
      type: object
      properties:
        Yaw:
          type: number
          description: Value representing eye direction on the yaw axis.
        Pitch:
          type: number
          description: Value representing eye direction on the pitch axis.
        Confidence:
          type: number
          description: The confidence that the service has in its predicted eye direction.
    EyeOpen:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the eyes on the face are open.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    Eyeglasses:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the face is wearing eye glasses or not.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    FaceDetail:
      type: object
      properties:
        BoundingBox:
          $ref: '#/components/schemas/BoundingBox'
        AgeRange:
          $ref: '#/components/schemas/AgeRange'
        Smile:
          $ref: '#/components/schemas/Smile'
        Eyeglasses:
          $ref: '#/components/schemas/Eyeglasses'
        Sunglasses:
          $ref: '#/components/schemas/Sunglasses'
        Gender:
          $ref: '#/components/schemas/Gender'
        Beard:
          $ref: '#/components/schemas/Beard'
        Mustache:
          $ref: '#/components/schemas/Mustache'
        EyesOpen:
          $ref: '#/components/schemas/EyeOpen'
        MouthOpen:
          $ref: '#/components/schemas/MouthOpen'
        Emotions:
          type: array
          items:
            $ref: '#/components/schemas/Emotion'
          description: The emotions that appear to be expressed on the face, and the confidence level in the determination.
            The API is only making a determination of the physical appearance of a person's face. It is not a determination
            of the person’s internal emotional state and should not be used in such a way. For example, a person pretending
            to have a sad face might not be sad emotionally.
        Landmarks:
          type: array
          items:
            $ref: '#/components/schemas/Landmark'
          description: Indicates the location of landmarks on the face. Default attribute.
        Pose:
          $ref: '#/components/schemas/Pose'
        Quality:
          $ref: '#/components/schemas/ImageQuality'
        Confidence:
          type: number
          description: Confidence level that the bounding box contains a face (and not a different object such as a tree).
            Default attribute.
        FaceOccluded:
          $ref: '#/components/schemas/FaceOccluded'
        EyeDirection:
          $ref: '#/components/schemas/EyeDirection'
    FaceOccluded:
      type: object
      properties:
        Value:
          type: boolean
          description: True if a detected face’s eyes, nose, and mouth are partially captured or if they are covered by masks,
            dark sunglasses, cell phones, hands, or other objects. False if common occurrences that do not impact face verification
            are detected, such as eye glasses, lightly tinted sunglasses, strands of hair, and others.
        Confidence:
          type: number
          description: The confidence that the service has detected the presence of a face occlusion.
    Gender:
      type: object
      properties:
        Value:
          type: string
          enum:
          - Male
          - Female
          description: The predicted gender of the face.
        Confidence:
          type: number
          description: Level of confidence in the prediction.
    Image:
      type: object
      properties:
        Bytes:
          type: string
          format: byte
          description: Blob of image bytes up to 5 MBs. Note that the maximum image size you can pass to DetectCustomLabels
            is 4MB.
        S3Object:
          $ref: '#/components/schemas/S3Object'
    ImageQuality:
      type: object
      properties:
        Brightness:
          type: number
          description: Value representing brightness of the face. The service returns a value between 0 and 100 (inclusive).
            A higher value indicates a brighter face image.
        Sharpness:
          type: number
          description: Value representing sharpness of the face. The service returns a value between 0 and 100 (inclusive).
            A higher value indicates a sharper face image.
    InternalServerError:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
        Logref:
          type: string
          description: A universally unique identifier (UUID) for the request.
    Landmark:
      type: object
      properties:
        Type:
          type: string
          enum:
          - eyeLeft
          - eyeRight
          - nose
          - mouthLeft
          - mouthRight
          - leftEyeBrowLeft
          - leftEyeBrowRight
          - leftEyeBrowUp
          - rightEyeBrowLeft
          - rightEyeBrowRight
          - rightEyeBrowUp
          - leftEyeLeft
          - leftEyeRight
          - leftEyeUp
          - leftEyeDown
          - rightEyeLeft
          - rightEyeRight
          - rightEyeUp
          - rightEyeDown
          - noseLeft
          - noseRight
          - mouthUp
          - mouthDown
          - leftPupil
          - rightPupil
          - upperJawlineLeft
          - midJawlineLeft
          - chinBottom
          - midJawlineRight
          - upperJawlineRight
          description: Type of landmark.
        X:
          type: number
          description: The x-coordinate of the landmark expressed as a ratio of the width of the image. The x-coordinate is
            measured from the left-side of the image. For example, if the image is 700 pixels wide and the x-coordinate of
            the landmark is at 350 pixels, this value is 0.5.
        Y:
          type: number
          description: The y-coordinate of the landmark expressed as a ratio of the height of the image. The y-coordinate
            is measured from the top of the image. For example, if the image height is 200 pixels and the y-coordinate of
            the landmark is at 50 pixels, this value is 0.25.
    ListUsersRequest:
      type: object
      properties:
        CollectionId:
          type: string
          description: The ID of an existing collection.
        MaxResults:
          type: integer
          description: Maximum number of UsersID to return.
        NextToken:
          type: string
          description: Pagingation token to receive the next set of UsersID.
      required:
      - CollectionId
    ListUsersResponse:
      type: object
      properties:
        Users:
          type: array
          items:
            $ref: '#/components/schemas/User'
          description: List of UsersID associated with the specified collection.
        NextToken:
          type: string
          description: A pagination token to be used with the subsequent request if the response is truncated.
    MatchedUser:
      type: object
      properties:
        UserId:
          type: string
          description: A provided ID for the UserID. Unique within the collection.
        UserStatus:
          type: string
          enum:
          - ACTIVE
          - UPDATING
          - CREATING
          - CREATED
          description: The status of the user matched to a provided FaceID.
    MouthOpen:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the mouth on the face is open or not.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    Mustache:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the face has mustache or not.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    Pose:
      type: object
      properties:
        Roll:
          type: number
          description: Value representing the face rotation on the roll axis.
        Yaw:
          type: number
          description: Value representing the face rotation on the yaw axis.
        Pitch:
          type: number
          description: Value representing the face rotation on the pitch axis.
    S3Object:
      type: object
      properties:
        Bucket:
          type: string
          description: Name of the S3 bucket.
        Name:
          type: string
          description: S3 object key name.
        Version:
          type: string
          description: If the bucket is versioning enabled, you can specify the object version.
    SearchUsersByImageRequest:
      type: object
      properties:
        CollectionId:
          type: string
          description: The ID of an existing collection containing the UserID.
        Image:
          $ref: '#/components/schemas/Image'
        UserMatchThreshold:
          type: number
          description: Specifies the minimum confidence in the UserID match to return. Default value is 80.
        MaxUsers:
          type: integer
          description: Maximum number of UserIDs to return.
        QualityFilter:
          type: string
          enum:
          - NONE
          - AUTO
          - LOW
          - MEDIUM
          - HIGH
          description: A filter that specifies a quality bar for how much filtering is done to identify faces. Filtered faces
            aren't searched for in the collection. The default value is NONE.
      required:
      - CollectionId
      - Image
    SearchUsersByImageResponse:
      type: object
      properties:
        UserMatches:
          type: array
          items:
            $ref: '#/components/schemas/UserMatch'
          description: An array of UserID objects that matched the input face, along with the confidence in the match. The
            returned structure will be empty if there are no matches. Returned if the SearchUsersByImageResponse action is
            successful.
        FaceModelVersion:
          type: string
          description: Version number of the face detection model associated with the input collection CollectionId.
        SearchedFace:
          $ref: '#/components/schemas/SearchedFaceDetails'
        UnsearchedFaces:
          type: array
          items:
            $ref: '#/components/schemas/UnsearchedFace'
          description: List of UnsearchedFace objects. Contains the face details infered from the specified image but not
            used for search. Contains reasons that describe why a face wasn't used for Search.
    SearchUsersRequest:
      type: object
      properties:
        CollectionId:
          type: string
          description: The ID of an existing collection containing the UserID, used with a UserId or FaceId. If a FaceId is
            provided, UserId isn’t required to be present in the Collection.
        UserId:
          type: string
          description: ID for the existing User.
        FaceId:
          type: string
          description: ID for the existing face.
        UserMatchThreshold:
          type: number
          description: Optional value that specifies the minimum confidence in the matched UserID to return. Default value
            of 80.
        MaxUsers:
          type: integer
          description: Maximum number of identities to return.
      required:
      - CollectionId
    SearchUsersResponse:
      type: object
      properties:
        UserMatches:
          type: array
          items:
            $ref: '#/components/schemas/UserMatch'
          description: An array of UserMatch objects that matched the input face along with the confidence in the match. Array
            will be empty if there are no matches.
        FaceModelVersion:
          type: string
          description: Version number of the face detection model associated with the input CollectionId.
        SearchedFace:
          $ref: '#/components/schemas/SearchedFace'
        SearchedUser:
          $ref: '#/components/schemas/SearchedUser'
    SearchedFace:
      type: object
      properties:
        FaceId:
          type: string
          description: Unique identifier assigned to the face.
    SearchedFaceDetails:
      type: object
      properties:
        FaceDetail:
          $ref: '#/components/schemas/FaceDetail'
    SearchedUser:
      type: object
      properties:
        UserId:
          type: string
          description: A provided ID for the UserID. Unique within the collection.
    Smile:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the face is smiling or not.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    Sunglasses:
      type: object
      properties:
        Value:
          type: boolean
          description: Boolean value that indicates whether the face is wearing sunglasses or not.
        Confidence:
          type: number
          description: Level of confidence in the determination.
    UnsearchedFace:
      type: object
      properties:
        FaceDetails:
          $ref: '#/components/schemas/FaceDetail'
        Reasons:
          type: array
          items:
            type: string
            enum:
            - FACE_NOT_LARGEST
            - EXCEEDS_MAX_FACES
            - EXTREME_POSE
            - LOW_BRIGHTNESS
            - LOW_SHARPNESS
            - LOW_CONFIDENCE
            - SMALL_BOUNDING_BOX
            - LOW_FACE_QUALITY
          description: Reasons why a face wasn't used for Search.
    User:
      type: object
      properties:
        UserId:
          type: string
          description: A provided ID for the User. Unique within the collection.
        UserStatus:
          type: string
          enum:
          - ACTIVE
          - UPDATING
          - CREATING
          - CREATED
          description: Communicates if the UserID has been updated with latest set of faces to be associated with the UserID.
    UserMatch:
      type: object
      properties:
        Similarity:
          type: number
          description: Describes the UserID metadata.
        User:
          $ref: '#/components/schemas/MatchedUser'
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/rekognition/service/2016-06-27/rekognition-2016-06-27.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)