# People API

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

Use your own server and its scoped API keys.

## Delete people

DELETE /api/people

Bulk delete a list of people at once.

```json
{
  "description": "Bulk delete a list of people at once.",
  "operationId": "deletePeople",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/BulkIdsDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Delete people",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.delete"
}
```

## Get all people

GET /api/people

Retrieve a list of all people.

```json
{
  "description": "Retrieve a list of all people.",
  "operationId": "getAllPeople",
  "parameters": [
    {
      "name": "closestAssetId",
      "required": false,
      "in": "query",
      "description": "Closest asset ID for similarity search",
      "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": "closestPersonId",
      "required": false,
      "in": "query",
      "description": "Closest person ID for similarity search",
      "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": "page",
      "required": false,
      "in": "query",
      "description": "Page number for pagination",
      "schema": {
        "minimum": 1,
        "maximum": 9007199254740991,
        "default": 1,
        "type": "integer"
      }
    },
    {
      "name": "size",
      "required": false,
      "in": "query",
      "description": "Number of items per page",
      "schema": {
        "minimum": 1,
        "maximum": 1000,
        "default": 500,
        "type": "integer"
      }
    },
    {
      "name": "withHidden",
      "required": false,
      "in": "query",
      "description": "Include hidden people",
      "schema": {
        "type": "boolean"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PeopleResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Get all people",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.read"
}
```

## Create a person

POST /api/people

Create a new person that can have multiple faces assigned to them.

```json
{
  "description": "Create a new person that can have multiple faces assigned to them.",
  "operationId": "createPerson",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PersonCreateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PersonResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Create a person",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.create"
}
```

## Update people

PUT /api/people

Bulk update multiple people at once.

```json
{
  "description": "Bulk update multiple people at once.",
  "operationId": "updatePeople",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PeopleUpdateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/BulkIdResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Update people",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.update"
}
```

## Undo a face correction

POST /api/people/corrections/{id}/undo

Reverse one manual face decision from the correction history, while the face still stands as the decision left it (same original, same place, same person). Otherwise 409 with a `reason`.

```json
{
  "description": "Reverse one manual face decision from the correction history, while the face still stands as the decision left it (same original, same place, same person). Otherwise 409 with a `reason`.",
  "operationId": "undoCorrection",
  "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"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PersonCorrectionDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Undo a face correction",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.update"
}
```

## Merge people

POST /api/people/merge

Merge an ordered list of people together into a single person. The final name and birth date are always the first defined value, following the order. Also automatically merges people for other users in the cluster group, skipping people that would result in overriding a previously set name or birth date.

```json
{
  "description": "Merge an ordered list of people together into a single person. The final name and birth date are always the first defined value, following the order. Also automatically merges people for other users in the cluster group, skipping people that would result in overriding a previously set name or birth date.",
  "operationId": "mergePeople",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MergePersonDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/BulkIdResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Merge people",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.merge"
}
```

## Get merge suggestions

GET /api/people/merge-suggestions

Retrieve suggested pairs of people that may be the same person, based on face similarity, for the guided merge review flow.

```json
{
  "description": "Retrieve suggested pairs of people that may be the same person, based on face similarity, for the guided merge review flow.",
  "operationId": "getMergeSuggestions",
  "parameters": [],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MergeSuggestionsResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Get merge suggestions",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.read"
}
```

## Undo a merge suggestion verdict

DELETE /api/people/merge-suggestions/verdicts

Remove the recorded verdict for a pair of people, so the pair can be suggested again. The same person id twice undoes "ignore" for that person.

```json
{
  "description": "Remove the recorded verdict for a pair of people, so the pair can be suggested again. The same person id twice undoes \"ignore\" for that person.",
  "operationId": "deleteMergeVerdict",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PersonMergeVerdictDeleteDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Undo a merge suggestion verdict",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.update"
}
```

## Record a merge suggestion verdict

PUT /api/people/merge-suggestions/verdicts

Answer a suggested pair of people: "same" merges them now, "different" never suggests the pair again, "later" skips it for 30 days and "ignore" stops suggesting `personId` with anyone. Replaces an earlier verdict for the same pair (a "later" never replaces a "different"); the pair may be given in either order.

```json
{
  "description": "Answer a suggested pair of people: \"same\" merges them now, \"different\" never suggests the pair again, \"later\" skips it for 30 days and \"ignore\" stops suggesting `personId` with anyone. Replaces an earlier verdict for the same pair (a \"later\" never replaces a \"different\"); the pair may be given in either order.",
  "operationId": "setMergeVerdict",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PersonMergeVerdictCreateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PersonMergeVerdictResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Record a merge suggestion verdict",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.update"
}
```

## Delete person

DELETE /api/people/{id}

Delete an individual person.

```json
{
  "description": "Delete an individual person.",
  "operationId": "deletePerson",
  "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"
      }
    }
  ],
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Delete person",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.delete"
}
```

## Get a person

GET /api/people/{id}

Retrieve a person by id.

```json
{
  "description": "Retrieve a person by id.",
  "operationId": "getPerson",
  "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"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PersonResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Get a person",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.read"
}
```

## Update person

PUT /api/people/{id}

Update an individual person.

```json
{
  "deprecated": true,
  "description": "Update an individual person.",
  "operationId": "updatePerson",
  "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/PersonUpdateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PersonResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Update person",
  "tags": [
    "People",
    "Deprecated"
  ],
  "x-frameleaf-permission": "person.update"
}
```

## Get correction history

GET /api/people/{id}/corrections

Retrieve the manual face decisions made about this person (faces moved onto or off them, "not a face of anyone", merges and moved face boxes), most recent first, a page at a time. Only the owner sees them. A photo that can no longer be shown (trashed, Locked, hidden) is left out of the evidence.

```json
{
  "description": "Retrieve the manual face decisions made about this person (faces moved onto or off them, \"not a face of anyone\", merges and moved face boxes), most recent first, a page at a time. Only the owner sees them. A photo that can no longer be shown (trashed, Locked, hidden) is left out of the evidence.",
  "operationId": "getCorrectionHistory",
  "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"
      }
    },
    {
      "name": "page",
      "required": false,
      "in": "query",
      "description": "Page number",
      "schema": {
        "minimum": 1,
        "maximum": 9007199254740991,
        "default": 1,
        "type": "integer"
      }
    },
    {
      "name": "size",
      "required": false,
      "in": "query",
      "description": "Number of decisions per page",
      "schema": {
        "minimum": 1,
        "maximum": 100,
        "default": 25,
        "type": "integer"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PersonCorrectionsResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Get correction history",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.read"
}
```

## Merge people

POST /api/people/{id}/merge

Merge a list of people into the person specified in the path parameter.

```json
{
  "deprecated": true,
  "description": "Merge a list of people into the person specified in the path parameter.",
  "operationId": "mergePersonLegacy",
  "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/MergePersonDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/BulkIdResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Merge people",
  "tags": [
    "People",
    "Deprecated"
  ],
  "x-frameleaf-permission": "person.merge"
}
```

## Reassign faces

PUT /api/people/{id}/reassign

Bulk reassign a list of faces to a different person.

```json
{
  "description": "Bulk reassign a list of faces to a different person.",
  "operationId": "reassignFaces",
  "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/AssetFaceUpdateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/PersonResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Reassign faces",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.reassign"
}
```

## Get person statistics

GET /api/people/{id}/statistics

Retrieve statistics about a specific person.

```json
{
  "description": "Retrieve statistics about a specific person.",
  "operationId": "getPersonStatistics",
  "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"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PersonStatisticsResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Get person statistics",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.statistics"
}
```

## Get person thumbnail

GET /api/people/{id}/thumbnail

Retrieve the thumbnail file for a person.

```json
{
  "description": "Retrieve the thumbnail file for a person.",
  "operationId": "getPersonThumbnail",
  "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"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/octet-stream": {
          "schema": {
            "format": "binary",
            "type": "string"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Get person thumbnail",
  "tags": [
    "People"
  ],
  "x-frameleaf-permission": "person.read"
}
```