> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/developers/search-and-ai/people-and-faces.md).

# People & faces

Facial recognition groups the faces Shade detects into individuals. Name an individual once, and you can find every asset they appear in.

To find assets with a person in them, call `POST /search` with an `individual` filter whose `options` contain the individual's ID.

## Get all the faces for an asset

> Get all the faces an asset contains

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/faces":{"get":{"tags":["people"],"summary":"Get all the faces for an asset","description":"Get all the faces an asset contains","operationId":"getAssetFaces","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The asset to get the faces for"},"description":"The asset to get the faces for"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FaceDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## List all individuals

> Get a list of all significant individuals. Note: an individual is only sig and returned if it contains >=1 faces.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"IndividualDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"preview_face":{"anyOf":[{"$ref":"#/components/schemas/FaceDTO"},{"type":"null"}]},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]}},"type":"object","required":["id","name"],"title":"IndividualDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals":{"get":{"tags":["people"],"summary":"List all individuals","description":"Get a list of all significant individuals. Note: an individual is only sig and returned if it contains >=1 faces.","operationId":"listIndividuals","parameters":[{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to get individuals for"},"description":"The id of the drive to get individuals for"},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page number","description":"The page to query","default":0},"description":"The page to query"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit per page","description":"The limit that is fetched per page","default":100},"description":"The limit that is fetched per page"},{"name":"labeled","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled individuals","description":"If set, only labeled individuals will be returned"},"description":"If set, only labeled individuals will be returned"}],"responses":{"200":{"description":"A list of all individuals","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IndividualDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Search individuals by name

> Search for individuals by name using trigram similarity.\
> Uses the GIN trigram index for efficient fuzzy matching.\
> Supports sorting by name or face count.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"IndividualDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"preview_face":{"anyOf":[{"$ref":"#/components/schemas/FaceDTO"},{"type":"null"}]},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]}},"type":"object","required":["id","name"],"title":"IndividualDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/search":{"get":{"tags":["people"],"summary":"Search individuals by name","description":"Search for individuals by name using trigram similarity.\nUses the GIN trigram index for efficient fuzzy matching.\nSupports sorting by name or face count.","operationId":"searchIndividuals","parameters":[{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to search individuals in"},"description":"The id of the drive to search individuals in"},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name query","description":"The name to search for (uses trigram similarity)"},"description":"The name to search for (uses trigram similarity)"},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page number","description":"The page to query","default":0},"description":"The page to query"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit per page","description":"The limit that is fetched per page","default":100},"description":"The limit that is fetched per page"},{"name":"sort_by","in":"query","required":false,"schema":{"enum":["name","face_count"],"type":"string","title":"Sort by","description":"Field to sort by: 'name' or 'face_count'","default":"face_count"},"description":"Field to sort by: 'name' or 'face_count'"},{"name":"sort_order","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","title":"Sort order","description":"Sort direction: 'asc' or 'desc'","default":"desc"},"description":"Sort direction: 'asc' or 'desc'"}],"responses":{"200":{"description":"A list of individuals matching the search query","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IndividualDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get an individual

> Get an individual by id

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"IndividualDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"preview_face":{"anyOf":[{"$ref":"#/components/schemas/FaceDTO"},{"type":"null"}]},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]}},"type":"object","required":["id","name"],"title":"IndividualDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{individual_id}":{"get":{"tags":["people"],"summary":"Get an individual","description":"Get an individual by id","operationId":"getIndividual","parameters":[{"name":"individual_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The individual id"},"description":"ID of the individual (a recognized person). List them with `GET /individuals`."}],"responses":{"200":{"description":"The individual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndividualDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update an individual

> Update an individual with a new name/label.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"UpdateIndividualRequest":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Individual label","description":"The new name/label for the individual"}},"type":"object","title":"UpdateIndividualRequest"},"IndividualDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"preview_face":{"anyOf":[{"$ref":"#/components/schemas/FaceDTO"},{"type":"null"}]},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]}},"type":"object","required":["id","name"],"title":"IndividualDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{individual_id}":{"put":{"tags":["people"],"summary":"Update an individual","description":"Update an individual with a new name/label.","operationId":"updateIndividual","parameters":[{"name":"individual_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The individual id","description":"The id of the individual to be updated"},"description":"The id of the individual to be updated"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIndividualRequest"}}}},"responses":{"200":{"description":"The updated individual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndividualDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get an individual with all details

> Get an individual with full details including profile attachment,\
> reference attachments, and assigned faces.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"IndividualDetailsDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"reference_attachments":{"items":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},"type":"array","title":"Reference Attachments","default":[]},"faces":{"items":{"$ref":"#/components/schemas/FaceDTO"},"type":"array","title":"Faces","default":[]}},"type":"object","required":["id","name"],"title":"IndividualDetailsDTO","description":"Extended individual DTO with full details including references and faces."},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{individual_id}/details":{"get":{"tags":["people"],"summary":"Get an individual with all details","description":"Get an individual with full details including profile attachment,\nreference attachments, and assigned faces.","operationId":"getIndividualDetails","parameters":[{"name":"individual_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The individual id"},"description":"ID of the individual (a recognized person). List them with `GET /individuals`."},{"name":"faces_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Maximum number of faces to return","title":"Faces Limit"},"description":"Maximum number of faces to return"},{"name":"faces_random_sample","in":"query","required":false,"schema":{"type":"boolean","description":"If true and faces_limit is set, returns a random sample of faces","default":false,"title":"Faces Random Sample"},"description":"If true and faces_limit is set, returns a random sample of faces"}],"responses":{"200":{"description":"The individual with profile, references, and faces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndividualDetailsDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete a reference attachment from an individual

> Delete a reference attachment from an individual and recalculate the centroid.\
> \
> The attachment's per-embedding is auto-deleted via CASCADE. We recompute the\
> attachment\_embedding from remaining stored embeddings without re-processing\
> through FR.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"IndividualDetailsDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"reference_attachments":{"items":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},"type":"array","title":"Reference Attachments","default":[]},"faces":{"items":{"$ref":"#/components/schemas/FaceDTO"},"type":"array","title":"Faces","default":[]}},"type":"object","required":["id","name"],"title":"IndividualDetailsDTO","description":"Extended individual DTO with full details including references and faces."},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{individual_id}/reference/{attachment_id}":{"delete":{"tags":["people"],"summary":"Delete a reference attachment from an individual","description":"Delete a reference attachment from an individual and recalculate the centroid.\n\nThe attachment's per-embedding is auto-deleted via CASCADE. We recompute the\nattachment_embedding from remaining stored embeddings without re-processing\nthrough FR.","operationId":"deleteIndividualReference","parameters":[{"name":"individual_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The individual id"},"description":"ID of the individual (a recognized person). List them with `GET /individuals`."},{"name":"attachment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The attachment id to delete"}}],"responses":{"200":{"description":"The updated individual details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndividualDetailsDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update the profile attachment for an individual

> Update the profile attachment for an individual.\
> Deletes the existing profile attachment (if any), links the new one,\
> and recalculates the centroid.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"UpdateIndividualProfileRequest":{"properties":{"profile_attachment_token":{"type":"string","title":"Profile attachment token","description":"JWT token for the new profile image attachment"}},"type":"object","required":["profile_attachment_token"],"title":"UpdateIndividualProfileRequest"},"IndividualDetailsDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"reference_attachments":{"items":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},"type":"array","title":"Reference Attachments","default":[]},"faces":{"items":{"$ref":"#/components/schemas/FaceDTO"},"type":"array","title":"Faces","default":[]}},"type":"object","required":["id","name"],"title":"IndividualDetailsDTO","description":"Extended individual DTO with full details including references and faces."},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{individual_id}/profile":{"put":{"tags":["people"],"summary":"Update the profile attachment for an individual","description":"Update the profile attachment for an individual.\nDeletes the existing profile attachment (if any), links the new one,\nand recalculates the centroid.","operationId":"updateIndividualProfile","parameters":[{"name":"individual_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The individual id"},"description":"ID of the individual (a recognized person). List them with `GET /individuals`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIndividualProfileRequest"}}}},"responses":{"200":{"description":"The updated individual details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndividualDetailsDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Add reference attachments to an individual

> Add new reference attachments to an existing individual and recalculate the centroid.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"AddIndividualReferencesRequest":{"properties":{"reference_attachment_tokens":{"items":{"type":"string"},"type":"array","title":"Reference attachment tokens","description":"JWT tokens for the new reference image attachments"}},"type":"object","required":["reference_attachment_tokens"],"title":"AddIndividualReferencesRequest"},"IndividualDetailsDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"reference_attachments":{"items":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},"type":"array","title":"Reference Attachments","default":[]},"faces":{"items":{"$ref":"#/components/schemas/FaceDTO"},"type":"array","title":"Faces","default":[]}},"type":"object","required":["id","name"],"title":"IndividualDetailsDTO","description":"Extended individual DTO with full details including references and faces."},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{individual_id}/references":{"post":{"tags":["people"],"summary":"Add reference attachments to an individual","description":"Add new reference attachments to an existing individual and recalculate the centroid.","operationId":"addIndividualReferences","parameters":[{"name":"individual_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The individual id"},"description":"ID of the individual (a recognized person). List them with `GET /individuals`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddIndividualReferencesRequest"}}}},"responses":{"200":{"description":"The updated individual details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndividualDetailsDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Hides the given individuals by id

> Hide individuals by their ids.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"HideIndividualsRequest":{"properties":{"individual_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Individual IDs","description":"The ids of the individuals to hide"}},"type":"object","required":["individual_ids"],"title":"HideIndividualsRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{drive_id}/individual/disable":{"put":{"tags":["people"],"summary":"Hides the given individuals by id","description":"Hide individuals by their ids.","operationId":"hideIndividuals","deprecated":true,"parameters":[{"name":"drive_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to hide individuals in"},"description":"The id of the drive to hide individuals in"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HideIndividualsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Permanently deletes the given individuals by id

> Permanently delete individuals by their ids.\
> \
> Faces associated with these individuals will be unassigned (not deleted)\
> and can be re-assigned to other individuals later.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"DeleteIndividualsRequest":{"properties":{"individual_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Individual IDs","description":"The ids of the individuals to delete"}},"type":"object","required":["individual_ids"],"title":"DeleteIndividualsRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{drive_id}/individual/delete":{"delete":{"tags":["people"],"summary":"Permanently deletes the given individuals by id","description":"Permanently delete individuals by their ids.\n\nFaces associated with these individuals will be unassigned (not deleted)\nand can be re-assigned to other individuals later.","operationId":"deleteIndividuals","parameters":[{"name":"drive_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to delete individuals from"},"description":"The id of the drive to delete individuals from"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteIndividualsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create an individual from faces

> Create an individual from a set of faces defined by the user.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"CreateIndividualFromFacesRequest":{"properties":{"face_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Face IDs","description":"The ids of the faces to create the individual from"},"individual_name":{"type":"string","title":"Individual name","description":"The name/label for the individual"},"old_individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Old Individual ID","description":"If provided, the individual that the faces are being taken from (must be a labeled individual)"}},"type":"object","required":["face_ids","individual_name"],"title":"CreateIndividualFromFacesRequest"},"IndividualDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"preview_face":{"anyOf":[{"$ref":"#/components/schemas/FaceDTO"},{"type":"null"}]},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]}},"type":"object","required":["id","name"],"title":"IndividualDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{drive_id}/individual/create":{"post":{"tags":["people"],"summary":"Create an individual from faces","description":"Create an individual from a set of faces defined by the user.","operationId":"createIndividualFromFaces","parameters":[{"name":"drive_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to create the individual in"},"description":"The id of the drive to create the individual in"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIndividualFromFacesRequest"}}}},"responses":{"200":{"description":"The new individual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndividualDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create an individual with manual attachments

> Create a labeled individual and attach manually uploaded reference images via attachments.\
> \
> This is used by the create-individual wizard:\
> \- The client first uploads images via /attachments/upload to obtain tokens\
> \- Those tokens are then passed here to be linked to the individual\
> \
> Note: embedding/face creation from these attachments is handled by follow-up jobs.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"CreateIndividualFromReferencesRequest":{"properties":{"individual_name":{"type":"string","title":"Individual name","description":"The name/label for the individual"},"profile_attachment_tokens":{"items":{"type":"string"},"type":"array","title":"Profile attachment tokens","description":"JWT tokens for the primary profile image attachments","default":[]},"reference_attachment_tokens":{"items":{"type":"string"},"type":"array","title":"Reference attachment tokens","description":"JWT tokens for additional reference image attachments","default":[]}},"type":"object","required":["individual_name"],"title":"CreateIndividualFromReferencesRequest"},"IndividualDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"preview_face":{"anyOf":[{"$ref":"#/components/schemas/FaceDTO"},{"type":"null"}]},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]}},"type":"object","required":["id","name"],"title":"IndividualDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{drive_id}/individual/create_manual":{"post":{"tags":["people"],"summary":"Create an individual with manual attachments","description":"Create a labeled individual and attach manually uploaded reference images via attachments.\n\nThis is used by the create-individual wizard:\n- The client first uploads images via /attachments/upload to obtain tokens\n- Those tokens are then passed here to be linked to the individual\n\nNote: embedding/face creation from these attachments is handled by follow-up jobs.","operationId":"createIndividualFromReferences","parameters":[{"name":"drive_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to create the individual in"},"description":"The id of the drive to create the individual in"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIndividualFromReferencesRequest"}}}},"responses":{"200":{"description":"The new individual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndividualDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Assign a face to another individual

> Assign face(s) to an individual.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"AssignFaceToIndividualRequest":{"properties":{"face_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Face IDs","description":"The id of the faces to assign"},"individual_id":{"type":"string","format":"uuid","title":"Individual ID","description":"The id of the individual to assign the face to (must be a labeled individual)"},"old_individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Old Individual ID","description":"If provided, the individual that the faces are being taken from (must be a labeled individual)"},"update_centroid":{"type":"boolean","title":"Update Centroid","description":"If true, updates the individual's centroid embedding with the assigned faces. Should only be true for manual user actions (e.g., verification step, manual reassignments).","default":false}},"type":"object","required":["face_ids","individual_id"],"title":"AssignFaceToIndividualRequest"},"IndividualDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"preview_face":{"anyOf":[{"$ref":"#/components/schemas/FaceDTO"},{"type":"null"}]},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]}},"type":"object","required":["id","name"],"title":"IndividualDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{drive_id}/individual/assign":{"put":{"tags":["people"],"summary":"Assign a face to another individual","description":"Assign face(s) to an individual.","operationId":"assignFaceToIndividual","parameters":[{"name":"drive_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to create the individual in"},"description":"The id of the drive to create the individual in"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignFaceToIndividualRequest"}}}},"responses":{"200":{"description":"The new individual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndividualDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Unassign faces from an individual and blacklist them

> Unassign face(s) from an individual and blacklist them so they won't be\
> re-clustered back into the same individual.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"UnassignFacesFromIndividualRequest":{"properties":{"face_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Face IDs","description":"The ids of the faces to unassign"},"individual_id":{"type":"string","format":"uuid","title":"Individual ID","description":"The id of the individual to unassign the faces from"}},"type":"object","required":["face_ids","individual_id"],"title":"UnassignFacesFromIndividualRequest"},"IndividualDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"preview_face":{"anyOf":[{"$ref":"#/components/schemas/FaceDTO"},{"type":"null"}]},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]}},"type":"object","required":["id","name"],"title":"IndividualDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{drive_id}/individual/unassign":{"put":{"tags":["people"],"summary":"Unassign faces from an individual and blacklist them","description":"Unassign face(s) from an individual and blacklist them so they won't be\nre-clustered back into the same individual.","operationId":"unassignFacesFromIndividual","parameters":[{"name":"drive_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive containing the individual"},"description":"The id of the drive containing the individual"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnassignFacesFromIndividualRequest"}}}},"responses":{"200":{"description":"The updated individual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndividualDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Merges individuals together into one

> Merge multiple individuals into one, combining their faces and setting a new name.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"MergeIndividualsRequest":{"properties":{"individual_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Individual IDs","description":"The ids of the individuals to merge"},"name":{"type":"string","title":"Name for combined individuals","description":"The new name given to the combined individuals"}},"type":"object","required":["individual_ids","name"],"title":"MergeIndividualsRequest"},"IndividualDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"preview_face":{"anyOf":[{"$ref":"#/components/schemas/FaceDTO"},{"type":"null"}]},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]}},"type":"object","required":["id","name"],"title":"IndividualDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{drive_id}/individual/merge":{"put":{"tags":["people"],"summary":"Merges individuals together into one","description":"Merge multiple individuals into one, combining their faces and setting a new name.","operationId":"mergeIndividuals","parameters":[{"name":"drive_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to get faces for"},"description":"The id of the drive to get faces for"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeIndividualsRequest"}}}},"responses":{"200":{"description":"The newly merged individual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndividualDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete unclustered faces

> Delete unclustered faces (faces not assigned to any individual).\
> This permanently removes them from the database.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"DeleteUnclusteredFacesRequest":{"properties":{"face_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Face IDs","description":"The IDs of unclustered faces to delete"}},"type":"object","required":["face_ids"],"title":"DeleteUnclusteredFacesRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{drive_id}/faces/unclustered":{"delete":{"tags":["people"],"summary":"Delete unclustered faces","description":"Delete unclustered faces (faces not assigned to any individual).\nThis permanently removes them from the database.","operationId":"deleteUnclusteredFaces","parameters":[{"name":"drive_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive containing the unclustered faces"},"description":"The id of the drive containing the unclustered faces"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteUnclusteredFacesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## List faces for an individual

> Get a paginated list of faces for an individual by id.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{individual_id}/faces":{"get":{"tags":["people"],"summary":"List faces for an individual","description":"Get a paginated list of faces for an individual by id.","operationId":"listIndividualFaces","parameters":[{"name":"individual_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The individual id","description":"The id of the individual to get faces for"},"description":"The id of the individual to get faces for"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Maximum number of faces to return","default":100,"title":"Limit"},"description":"Maximum number of faces to return"},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Number of faces to skip","default":0,"title":"Offset"},"description":"Number of faces to skip"}],"responses":{"200":{"description":"A list of faces for an individual","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FaceDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Suggest faces that may belong to an individual

> Return likely face matches for an individual using its embedding and unclustered faces.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/individuals/{drive_id}/individual/{individual_id}/verify_candidates":{"get":{"tags":["people"],"summary":"Suggest faces that may belong to an individual","description":"Return likely face matches for an individual using its embedding and unclustered faces.","operationId":"listIndividualCandidateFaces","parameters":[{"name":"drive_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to search faces in"},"description":"The id of the drive to search faces in"},{"name":"individual_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The individual id","description":"The id of the individual to suggest faces for"},"description":"The id of the individual to suggest faces for"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","title":"Result limit","description":"Maximum number of candidate faces to return","default":12},"description":"Maximum number of candidate faces to return"}],"responses":{"200":{"description":"A list of candidate faces for verification","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FaceDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get the individual a face is for

> Get the individual that a face is for by id

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"IndividualDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"labeled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Labeled"},"preview_face":{"anyOf":[{"$ref":"#/components/schemas/FaceDTO"},{"type":"null"}]},"profile_attachment":{"anyOf":[{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},{"type":"null"}]},"preview_image":{"anyOf":[{"$ref":"#/components/schemas/PreviewDTO"},{"type":"null"}]}},"type":"object","required":["id","name"],"title":"IndividualDTO"},"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/faces/{face_id}/individual":{"get":{"tags":["people"],"summary":"Get the individual a face is for","description":"Get the individual that a face is for by id","operationId":"getFaceIndividual","parameters":[{"name":"face_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The face id","description":"The id of the face whose individual to get"},"description":"The id of the face whose individual to get"}],"responses":{"200":{"description":"The individual","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndividualDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get the asset a face is for

> Get the asset that a face is for by id

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"AssetDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"path":{"type":"string","title":"Path"},"name":{"type":"string","title":"Name"},"extension":{"type":"string","title":"Extension"},"updated":{"type":"string","format":"date-time","title":"Updated"},"created":{"type":"string","format":"date-time","title":"Created"},"type":{"$ref":"#/components/schemas/AssetType"},"size_bytes":{"type":"integer","title":"Size Bytes"},"stack_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Stack Id"},"stack_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stack Number"},"is_fs_draft_blob":{"type":"boolean","title":"Is Fs Draft Blob"},"is_fs_null_blob":{"type":"boolean","title":"Is Fs Null Blob"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"ai_indexed":{"type":"boolean","title":"Ai Indexed"},"system_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"System Metadata","default":{}},"custom_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Custom Metadata","default":{}},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"palette":{"items":{"items":{"type":"integer"},"type":"array"},"type":"array","title":"Palette"},"ocr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ocr"},"transcription_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Transcription Id"},"faces_present":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Faces Present"},"content_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Content Length"},"comment_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Comment Count"},"preview_job_state":{"$ref":"#/components/schemas/JobState"},"metadata_job_state":{"$ref":"#/components/schemas/JobState"},"custom_metadata_job_state":{"$ref":"#/components/schemas/JobState"},"core_vision_job_state":{"$ref":"#/components/schemas/JobState"},"color_palette_job_state":{"$ref":"#/components/schemas/JobState"},"core_audio_job_state":{"$ref":"#/components/schemas/JobState"},"audio_job_state":{"$ref":"#/components/schemas/JobState"},"facial_recognition_job_state":{"$ref":"#/components/schemas/JobState"},"proxy_job_state":{"$ref":"#/components/schemas/JobState"},"audio_proxy_job_state":{"$ref":"#/components/schemas/JobState"},"transcription_job_state":{"$ref":"#/components/schemas/JobState"},"scrub_sheet_job_state":{"$ref":"#/components/schemas/JobState"},"objects":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Objects"},"texture_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Texture Data"},"integration_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Integration Data"},"preview_images":{"items":{"$ref":"#/components/schemas/PreviewDTO"},"type":"array","title":"Preview Images"},"custom_thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}]},"proxy":{"anyOf":[{"$ref":"#/components/schemas/ProxyDTO"},{"type":"null"}]},"audio_proxy":{"anyOf":[{"$ref":"#/components/schemas/ProxyDTO"},{"type":"null"}]},"scrub_sheet":{"anyOf":[{"$ref":"#/components/schemas/ScrubSheetDTO"},{"type":"null"}]},"grid_scrub_sheet":{"anyOf":[{"$ref":"#/components/schemas/ScrubSheetDTO"},{"type":"null"}]}},"type":"object","required":["id","drive_id","path","name","extension","updated","created","type","size_bytes","is_fs_draft_blob","is_fs_null_blob","ai_indexed","palette","preview_job_state","metadata_job_state","custom_metadata_job_state","core_vision_job_state","color_palette_job_state","core_audio_job_state","facial_recognition_job_state","proxy_job_state","audio_proxy_job_state","transcription_job_state","scrub_sheet_job_state","preview_images"],"title":"AssetDTO","description":"Full asset DTO with relationship fields that require eager loading."},"AssetType":{"type":"string","enum":["IMAGE","VIDEO","AUDIO","DOCUMENT","HDR","HDRI","PHOTOSHOP","ILLUSTRATOR","EXR","OBJECT","VECTOR","OTHER","MAYA","MAX","BLENDER","HOUDINI","UNREAL","UNITY","AFTER_EFFECTS","MOGRT"],"title":"AssetType"},"JobState":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","COMPLETED","FAILED","INSUFFICIENT_CREDITS"],"title":"JobState","description":"The state of a processing job on an asset, such as previews or transcription."},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"ProxyDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"}},"type":"object","required":["id"],"title":"ProxyDTO"},"ScrubSheetDTO":{"properties":{"preview_width":{"type":"integer","title":"Preview Width"},"preview_height":{"type":"integer","title":"Preview Height"},"columns":{"type":"integer","title":"Columns"},"rows":{"type":"integer","title":"Rows"},"interval":{"type":"number","title":"Interval"},"total_frames":{"type":"integer","title":"Total Frames"},"scrub_sheets":{"items":{"type":"string"},"type":"array","title":"Scrub Sheets"}},"type":"object","required":["preview_width","preview_height","columns","rows","interval","total_frames","scrub_sheets"],"title":"ScrubSheetDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/faces/{face_id}/asset":{"get":{"tags":["people"],"summary":"Get the asset a face is for","description":"Get the asset that a face is for by id","operationId":"getFaceAsset","parameters":[{"name":"face_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The face id","description":"The id of the face whose asset to get"},"description":"The id of the face whose asset to get"}],"responses":{"200":{"description":"The asset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /faces

> List all unclustered faces

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"people","description":"Facial recognition groups the faces Shade detects into individuals. Name an\nindividual once, and you can find every asset they appear in.\n\nTo find assets with a person in them, call `POST /search` with an\n`individual` filter whose `options` contain the individual's ID."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"FaceDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"bbox":{"additionalProperties":{"type":"integer"},"type":"object","title":"Bbox"},"face_preview":{"$ref":"#/components/schemas/PreviewDTO"},"individual_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Individual Id"}},"type":"object","required":["id","bbox","face_preview"],"title":"FaceDTO"},"PreviewDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"frame":{"type":"integer","title":"Frame"},"signed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signed Url"}},"type":"object","required":["id","frame"],"title":"PreviewDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/faces":{"get":{"tags":["people"],"summary":"List all unclustered faces","operationId":"listUnclusteredFaces","deprecated":true,"parameters":[{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"Drive ID","description":"The drive id to list faces for"},"description":"The drive id to list faces for"},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page number","description":"The page to query","default":0},"description":"The page to query"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit per page","description":"The limit that is fetched per page","default":100},"description":"The limit that is fetched per page"}],"responses":{"200":{"description":"List of all unclustered faces","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FaceDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://academy.shade.inc/developers/search-and-ai/people-and-faces.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
