# Faces API

Source: https://frameleaf.app/docs/api/reference/faces/

Use your own server and its scoped API keys.

## Retrieve faces for asset

GET /api/faces

Retrieve all faces belonging to an asset.

```json
{
  "description": "Retrieve all faces belonging to an asset.",
  "operationId": "getFaces",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "query",
      "description": "Face ID",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "withHidden",
      "required": false,
      "in": "query",
      "description": "Also list faces the asset's owner hid (owner only)",
      "schema": {
        "type": "boolean"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/AssetFaceResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve faces for asset",
  "tags": [
    "Faces"
  ],
  "x-frameleaf-permission": "face.read"
}
```

## Create a face

POST /api/faces

Create a new face that has not been discovered by facial recognition. The content of the bounding box is considered a face.

```json
{
  "description": "Create a new face that has not been discovered by facial recognition. The content of the bounding box is considered a face.",
  "operationId": "createFace",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AssetFaceCreateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AssetFaceResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Create a face",
  "tags": [
    "Faces"
  ],
  "x-frameleaf-permission": "face.create"
}
```

## Retrieve the face source revision for an asset

GET /api/faces/source

Retrieve the revision of the image faces are drawn on. Send it back as expectedSourceRevision when creating or moving a face; it changes when the image, its orientation or its edits change.

```json
{
  "description": "Retrieve the revision of the image faces are drawn on. Send it back as expectedSourceRevision when creating or moving a face; it changes when the image, its orientation or its edits change.",
  "operationId": "getFaceSource",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "query",
      "description": "Face ID",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AssetFaceSourceResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve the face source revision for an asset",
  "tags": [
    "Faces"
  ],
  "x-frameleaf-permission": "face.read"
}
```

## Delete a face

DELETE /api/faces/{id}

Delete a face identified by the id. Optionally can be force deleted.

```json
{
  "description": "Delete a face identified by the id. Optionally can be force deleted.",
  "operationId": "deleteFace",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AssetFaceDeleteDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Delete a face",
  "tags": [
    "Faces"
  ],
  "x-frameleaf-permission": "face.delete"
}
```

## Correct a face

PATCH /api/faces/{id}

Reassign or unassign a face, move or resize it, or hide it and show it again. The correction is refused with 409 when the face (or, for a box, the image) changed since expectedRevision.

```json
{
  "description": "Reassign or unassign a face, move or resize it, or hide it and show it again. The correction is refused with 409 when the face (or, for a box, the image) changed since expectedRevision.",
  "operationId": "correctFace",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AssetFaceCorrectionDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AssetFaceResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Correct a face",
  "tags": [
    "Faces"
  ],
  "x-frameleaf-permission": "face.update"
}
```

## Re-assign a face to another person

PUT /api/faces/{id}

Re-assign the face provided in the body to the person identified by the id in the path parameter.

```json
{
  "description": "Re-assign the face provided in the body to the person identified by the id in the path parameter.",
  "operationId": "reassignFacesById",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/FaceDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PersonResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Re-assign a face to another person",
  "tags": [
    "Faces"
  ],
  "x-frameleaf-permission": "face.update"
}
```