Persons are registered persons that you can later search for using face images. Registering a person allows you to search for them later using the `/search` endpoint. You can also use the `/person` endpoint(s) to update the registered person's name and/or add additional images to the registered person. Registering a person stores thumbnail face images and information on our servers. You can delete a registered person using the `DELETE /person/{person_id}` endpoint.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/seventh-sense:seventh-sense-persons-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: OpenCV Face Recognition Persons API
description: OpenCV Face Recognition allows you to either **manually** (through our Developer Portal UI) or **programmatically** (through our SDKs or REST API) detect, recognize, and verify faces in images.
version: 2026.07.15.0759
tags:
- name: Persons
description: Persons are registered persons that you can later search for using face images. Registering a person allows you to search for them later using the `/search` endpoint. You can also use the `/person` endpoint(s) to update the registered person's name and/or add additional images to the registered person. Registering a person stores thumbnail face images and information on our servers. You can delete a registered person using the `DELETE /person/{person_id}` endpoint.
paths:
/person/{person_id}:
get:
tags:
- Persons
summary: Get Person
operationId: get_person_person__person_id__get
security:
- APIKeyHeader: []
parameters:
- name: person_id
in: path
required: true
schema:
title: Person Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PersonSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Persons
summary: Delete Person
operationId: delete_person_person__person_id__delete
security:
- APIKeyHeader: []
parameters:
- name: person_id
in: path
required: true
schema:
title: Person Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DeletedItemSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/persons:
patch:
tags:
- Persons
summary: Modify Persons
operationId: modify_persons_persons_patch
security:
- APIKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeletePersonsSchema'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DeletedItemSchema'
title: Response Modify Persons Persons Patch
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Persons
summary: Get Persons
operationId: get_persons_persons_get
security:
- APIKeyHeader: []
parameters:
- name: skip
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Skip
- name: take
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 0
default: 20
title: Take
- name: order
in: query
required: false
schema:
allOf:
- $ref: '#/components/schemas/OrderEnum'
default: ASC
title: Order
- name: order_by
in: query
required: false
schema:
allOf:
- $ref: '#/components/schemas/PersonsOrderByEnum'
default: name
title: Order By
- name: search
in: query
required: false
schema:
type: string
title: Search
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ListPersonsSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/person:
post:
tags:
- Persons
summary: Create Person
operationId: create_person_person_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePersonSchema'
required: true
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PersonSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
patch:
tags:
- Persons
summary: Update Person
operationId: update_person_person_patch
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePersonSchema'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PersonSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
/person/crops:
post:
tags:
- Persons
summary: Create Person From Crops Obtained Using Detect End Point
operationId: create_person_from_crops_obtained_using_detect_end_point_person_crops_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePersonSchema'
required: true
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PersonSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
/person/images:
post:
tags:
- Persons
summary: Add Thumbnails From Images
operationId: add_thumbnails_from_images_person_images_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateImagesSchema'
required: true
responses:
'201':
description: Successful Response
content:
application/json:
schema:
items:
$ref: '#/components/schemas/CreateImageResponseSchema'
type: array
title: Response Add Thumbnails From Images Person Images Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
patch:
tags:
- Persons
summary: Update Person And Add New Images While Removing Old Ones
operationId: update_person_and_add_new_images_while_removing_old_ones_person_images_patch
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePersonAndImagesSchema'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PersonSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
/person/image/{person_id}/{thumbnail_id}:
delete:
tags:
- Persons
summary: Delete An Existing Thumbnail
operationId: delete_an_existing_thumbnail_person_image__person_id___thumbnail_id__delete
security:
- APIKeyHeader: []
parameters:
- name: person_id
in: path
required: true
schema:
title: Person Id
- name: thumbnail_id
in: path
required: true
schema:
title: Thumbnail Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DeletedItemSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/persons/{collection_id}:
get:
tags:
- Persons
summary: Get Persons In Collection
operationId: get_persons_in_collection_persons__collection_id__get
security:
- APIKeyHeader: []
parameters:
- name: collection_id
in: path
required: true
schema:
title: Collection Id
- name: skip
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Skip
- name: take
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 0
default: 20
title: Take
- name: order
in: query
required: false
schema:
allOf:
- $ref: '#/components/schemas/OrderEnum'
default: ASC
title: Order
- name: order_by
in: query
required: false
schema:
allOf:
- $ref: '#/components/schemas/PersonsOrderByEnum'
default: name
title: Order By
- name: search
in: query
required: false
schema:
type: string
title: Search
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ListPersonsSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
CollectionSchema:
properties:
id:
type: string
maxLength: 36
minLength: 36
title: Id
name:
type: string
maxLength: 50
minLength: 1
title: Name
description:
anyOf:
- type: string
maxLength: 100
minLength: 0
- type: 'null'
title: Description
count:
type: integer
title: Count
create_date:
type: string
format: date-time
title: Create Date
modified_date:
type: string
format: date-time
title: Modified Date
type: object
required:
- id
- name
- count
- create_date
- modified_date
title: CollectionSchema
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
DeletePersonsSchema:
properties:
action:
$ref: '#/components/schemas/ActionEnum'
person_ids:
items:
type: string
type: array
minItems: 1
title: Person Ids
type: object
required:
- action
- person_ids
title: DeletePersonsSchema
UpdatePersonAndImagesSchema:
properties:
id:
type: string
maxLength: 100
minLength: 1
title: Id
name:
anyOf:
- type: string
maxLength: 100
minLength: 1
- type: 'null'
title: Name
new_images:
anyOf:
- items:
type: string
type: array
maxItems: 3
minItems: 1
- type: 'null'
title: New Images
removed_thumbnail_ids:
anyOf:
- items:
type: string
type: array
minItems: 1
- type: 'null'
title: Removed Thumbnail Ids
gender:
anyOf:
- $ref: '#/components/schemas/GenderEnum'
- type: 'null'
date_of_birth:
anyOf:
- type: string
format: date
- type: 'null'
title: Date Of Birth
nationality:
anyOf:
- type: string
- type: 'null'
title: Nationality
collections:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Collections
notes:
anyOf:
- type: string
maxLength: 500
minLength: 0
- type: 'null'
title: Notes
type: object
required:
- id
title: UpdatePersonAndImagesSchema
example:
collections:
- string
date_of_birth: '2026-07-21'
gender: M
id: string
name: string
nationality: string
new_images:
- base64_encoded_string
notes: string
removed_thumbnail_ids:
- string
CreatePersonSchema:
properties:
id:
anyOf:
- type: string
maxLength: 100
minLength: 1
- type: 'null'
title: Id
name:
anyOf:
- type: string
maxLength: 100
minLength: 1
- type: 'null'
title: Name
images:
items:
type: string
type: array
maxItems: 3
minItems: 1
title: Images
gender:
anyOf:
- $ref: '#/components/schemas/GenderEnum'
- type: 'null'
date_of_birth:
anyOf:
- type: string
format: date
- type: 'null'
title: Date Of Birth
nationality:
anyOf:
- type: string
- type: 'null'
title: Nationality
collections:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Collections
notes:
anyOf:
- type: string
maxLength: 500
minLength: 0
- type: 'null'
title: Notes
is_bulk_insert:
anyOf:
- type: boolean
- type: 'null'
title: Is Bulk Insert
default: false
type: object
required:
- images
title: CreatePersonSchema
example:
collections:
- string
date_of_birth: '2026-07-21'
gender: M
id: string
images:
- base64_encoded_string
is_bulk_insert: false
name: string
nationality: string
notes: string
OrderEnum:
type: string
enum:
- ASC
- DESC
title: OrderEnum
GenderEnum:
type: string
enum:
- M
- F
title: GenderEnum
UpdatePersonSchema:
properties:
id:
type: string
maxLength: 100
minLength: 1
title: Id
name:
anyOf:
- type: string
maxLength: 100
minLength: 1
- type: 'null'
title: Name
images:
anyOf:
- items:
type: string
type: array
maxItems: 3
minItems: 1
- type: 'null'
title: Images
gender:
anyOf:
- $ref: '#/components/schemas/GenderEnum'
- type: 'null'
date_of_birth:
anyOf:
- type: string
format: date
- type: 'null'
title: Date Of Birth
nationality:
anyOf:
- type: string
- type: 'null'
title: Nationality
collections:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Collections
notes:
anyOf:
- type: string
maxLength: 500
minLength: 0
- type: 'null'
title: Notes
type: object
required:
- id
title: UpdatePersonSchema
example:
collections:
- string
date_of_birth: '2026-07-21'
gender: M
id: string
images:
- base64_encoded_string
name: string
nationality: string
notes: string
DeletedItemSchema:
properties:
id:
type: string
title: Id
type: object
title: DeletedItemSchema
ActionEnum:
type: string
const: DELETE
title: ActionEnum
PersonSchema:
properties:
id:
type: string
maxLength: 100
minLength: 1
title: Id
name:
anyOf:
- type: string
maxLength: 100
minLength: 1
- type: 'null'
title: Name
thumbnails:
items:
$ref: '#/components/schemas/ThumbnailSchema'
type: array
title: Thumbnails
gender:
anyOf:
- $ref: '#/components/schemas/GenderEnum'
- type: 'null'
date_of_birth:
anyOf:
- type: string
format: date
- type: 'null'
title: Date Of Birth
nationality:
anyOf:
- type: string
- type: 'null'
title: Nationality
collections:
items:
$ref: '#/components/schemas/CollectionSchema'
type: array
title: Collections
notes:
anyOf:
- type: string
maxLength: 500
minLength: 0
- type: 'null'
title: Notes
create_date:
type: string
format: date-time
title: Create Date
modified_date:
type: string
format: date-time
title: Modified Date
type: object
required:
- id
- collections
- create_date
- modified_date
title: PersonSchema
CreateImagesSchema:
properties:
person_id:
type: string
maxLength: 100
minLength: 1
title: Person Id
images:
items:
type: string
type: array
maxItems: 3
minItems: 1
title: Images
type: object
required:
- person_id
- images
title: CreateImagesSchema
example:
images:
- base64_encoded_string
person_id: string
PersonsOrderByEnum:
type: string
enum:
- name
- date_of_birth
- gender
- nationality
- modified_date
- create_date
title: PersonsOrderByEnum
CreateImageResponseSchema:
properties:
id:
type: string
title: Id
person_id:
type: string
title: Person Id
thumbnail:
type: string
title: Thumbnail
type: object
required:
- id
- person_id
- thumbnail
title: CreateImageResponseSchema
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ThumbnailSchema:
properties:
id:
type: string
title: Id
thumbnail:
type: string
title: Thumbnail
type: object
required:
- id
title: ThumbnailSchema
ListPersonsSchema:
properties:
count:
type: integer
title: Count
persons:
items:
$ref: '#/components/schemas/PersonSchema'
type: array
title: Persons
type: object
required:
- count
- persons
title: ListPersonsSchema
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: x-api-key