Documentation Powered by ReDoc

Luna-Faces API (v.4.1.0)

Download OpenAPI specification:Download

'VisionLabs Luna-Faces'

Service is intended for creation and management following entities:

  1. Temporary attributes. A temporary attribute is represented by the following fields:
    • basic attributes: age, gender, ethnicity and sample id list. Service supposes that basic attributes are as aggregated as a descriptor - from all samples.
    • list of descriptors with difference versions. Service supposes that each descriptor was aggregated from all samples
    • account id - the attribute owner
    • ttl - time to store the attribute in the service
  2. Face. A Face is an user logical entity. A Face contains the following fields:
    • user data - some string which user associates with the face
    • create time - time of the face creation
    • event id - event id associated with the face creation.
    • external id - user defined external id (non unique)
    • face attributes - basic attributes, list of descriptors difference version and corresponding samples ids.
    • account id - the face owner
  3. Lists. The Luna-Faces list is user defined list of faces. Each list is determined by the following data:
    • user data - some string which user associates with the list
    • create time - time of the list creation
    • last update time - time of last attachment or detachment of a face from the list
    • faces - list of faces attached to the list

version

get version

get service version

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "api": 1,
  • "major": 0,
  • "minor": 0,
  • "patch": 0
}

faces

create face

Create a new face.

The face can be attached to one or several lists.

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Request Body schema:
application/json
application/json
application/msgpack
account_id
required
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

id of the luna account.

event_id
string <uuid> (event_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

the event ID associated with the face creation

external_id
string (external_id) <= 36 characters

user-defined external id for face.

user_data
string (user_data) <= 128 characters
Default: ""

user data.

avatar
string <uri> (avatar) <= 256 characters
Default: ""

avatar for face, references to a sample or a user-defined reference.

lists
Array of strings <uuid> (list_id) [ 1 .. 1000 ] items

luna lists for linking face with them.

(attribute_no_account (attribute_with_descriptors_and_basic_attributes_no_account (object) or attribute_with_basic_attributes_no_account (object) or attribute_with_descriptors_no_account (object))) or attribute_set_by_attribute_id (object) (face_attribute)

face attribute. The attribute can be specified by temporary attribute ID or explicitly by attribute data.

Responses

Request samples

Content type
application/json
application/json
application/msgpack
Example
create face with attribute specified by attribute data
create face with attribute specified by attribute data
create face with attribute specified by attribute id
{
  • "account_id": "0468ca85-f6ca-4841-b30c-5ccc26b6f397",
  • "event_id": "557d54ec-29ad-4f3c-93b4-c9092ef12515",
  • "external_id": "2xQ2gprbMUePw1s9gw9fvA==",
  • "user_data": "some_string",
  • "avatar": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c4/Abbey_Lee_2015.jpg/800px-Abbey_Lee_2015.jpg",
  • "lists": [
    ],
  • "attribute": {
    }
}

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "face_id": "b5d6fd45-fcca-453d-ac05-3e594054b813",
  • "url": "/2/faces/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

get faces

Get faces according to filters.

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

create_time__lt
string <date-time> (time)
Example: create_time__lt=2018-08-11T09:11:41.674Z

upper bound for object create_time.

create_time__gte
string <date-time> (time)
Example: create_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object create_time.

event_id
string <uuid>

the event ID associated with the face creation.

face_ids
string <list of uuid>

list of comma-separated face ids.

face_id__lt
string <uuid>

upper face id excluding boundary.

face_id__gte
string <uuid>

lower face id including boundary.

external_ids
string <list of strings>

list of comma-separated external ids.

user_data
string
Example: user_data=user_data_text

find all objects with user_data that is similar to this parameter. You can specify some part of the user_data value for this filter.

list_id
string <uuid> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: list_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

id of a list that contains faces.

targets
string
Default: "face_id,account_id,event_id,external_id,user_data,create_time,avatar,lists"
Example: targets=face_id,user_data

Comma-separated list of face target fields. Available targets: face_id, account_id, event_id, external_id, user_data, create_time, avatar, lists

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{}

delete faces

Delete several faces.

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

ignore
integer
Default: 0
Enum: 0 1

whether to ignore some face does not exist

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Request Body schema:
application/json
application/json
application/msgpack
face_ids
required
Array of strings <uuid> (face_id) [ 1 .. 1000 ] items

ids of faces for removal

Responses

Request samples

Content type
application/json
application/json
application/msgpack
{
  • "face_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "error_code": 12022,
  • "desc": "Bad/incomplete input data",
  • "detail": "Failed to validate input json. Path: '', message: 'Additional properties are not allowed ('faces' was unexpected)'"
}

get face count

get face count

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

create_time__lt
string <date-time> (time)
Example: create_time__lt=2018-08-11T09:11:41.674Z

upper bound for object create_time.

create_time__gte
string <date-time> (time)
Example: create_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object create_time.

event_id
string <uuid>

the event ID associated with the face creation.

face_ids
string <list of uuid>

list of comma-separated face ids.

face_id__lt
string <uuid>

upper face id excluding boundary.

face_id__gte
string <uuid>

lower face id including boundary.

external_ids
string <list of strings>

list of comma-separated external ids.

user_data
string
Example: user_data=user_data_text

find all objects with user_data that is similar to this parameter. You can specify some part of the user_data value for this filter.

list_id
string <uuid> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: list_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

id of a list that contains faces.

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "faces_count": 146
}

get count of faces with attributes

count faces with attributes

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "faces_count": 146
}

put face

Put face.

The face can be attached to one or several lists.

path Parameters
face_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

ID of the face (face_id received in the "create face" request).

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Request Body schema:
application/json
application/json
application/msgpack
account_id
required
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

id of the luna account.

event_id
string <uuid> (event_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

the event ID associated with the face creation

external_id
string (external_id) <= 36 characters

user-defined external id for face.

user_data
string (user_data) <= 128 characters
Default: ""

user data.

avatar
string <uri> (avatar) <= 256 characters
Default: ""

avatar for face, references to a sample or a user-defined reference.

lists
Array of strings <uuid> (list_id) [ 1 .. 1000 ] items

luna lists for linking face with them.

(attribute_no_account (attribute_with_descriptors_and_basic_attributes_no_account (object) or attribute_with_basic_attributes_no_account (object) or attribute_with_descriptors_no_account (object))) or attribute_set_by_attribute_id (object) (face_attribute)

face attribute. The attribute can be specified by temporary attribute ID or explicitly by attribute data.

Responses

Request samples

Content type
application/json
application/json
application/msgpack
Example
put face with attribute specified by attribute data
put face with attribute specified by attribute data
put face with attribute specified by attribute id
{
  • "account_id": "0468ca85-f6ca-4841-b30c-5ccc26b6f397",
  • "event_id": "557d54ec-29ad-4f3c-93b4-c9092ef12515",
  • "external_id": "2xQ2gprbMUePw1s9gw9fvA==",
  • "user_data": "some_string",
  • "avatar": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c4/Abbey_Lee_2015.jpg/800px-Abbey_Lee_2015.jpg",
  • "lists": [
    ],
  • "attribute": {
    }
}

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "face_id": "b5d6fd45-fcca-453d-ac05-3e594054b813",
  • "url": "/2/faces/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

get face

Get face by ID.

NOTE: To get the face attribute data use method GET on /faces/{face_id}/attributes.

path Parameters
face_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

ID of the face (face_id received in the "create face" request).

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

targets
string
Default: "face_id,account_id,event_id,external_id,user_data,create_time,avatar,lists"
Example: targets=face_id,user_data

Comma-separated list of face target fields. Available targets: face_id, account_id, event_id, external_id, user_data, create_time, avatar, lists

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{}

check face existence

Check existence of the face by ID.

path Parameters
face_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

ID of the face (face_id received in the "create face" request).

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'account_id'"
}

update face

Update face fields: user_data, avatar, external_id, event_id.

NOTE: To update the face attribute data use method PATCH on /faces/{face_id}/attributes.

path Parameters
face_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

ID of the face (face_id received in the "create face" request).

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Request Body schema:
application/json
application/json
application/msgpack
event_id
string <uuid> Nullable ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

the event ID associated with the face creation

external_id
string (external_id) <= 36 characters

user-defined external id for face.

user_data
string (user_data) <= 128 characters
Default: ""

user data.

avatar
string <uri> (avatar) <= 256 characters
Default: ""

avatar for face, references to a sample or a user-defined reference.

Responses

Request samples

Content type
application/json
application/json
application/msgpack
{}

Response samples

Content type
application/json
Example
bad_content_type
bad_content_type
bad_query_param
bad_json
{
  • "error_code": 12017,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad content type"
}

delete face

Remove face by ID.

path Parameters
face_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

ID of the face (face_id received in the "create face" request).

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'account_id'"
}

face attributes

put face attribute

Put face attribute.

The attribute can be specified by temporary attribute ID or explicitly by attribute data.

path Parameters
face_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

ID of the face (face_id received in the "create face" request).

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Request Body schema:
application/json
application/json
application/msgpack
One of
One of
required
object (basic_attributes)

basic attributes. Each basic attribute was aggregated from the samples. Samples is needed for re-extract attributes of new algorithm version and visualisation.

basic_attributes_samples
Array of strings <uuid> (attributes_samples) [ 0 .. 1000 ] items unique
Default: []

list of uniqie sample ids which are resources for estimation attributes.

WARNING: if user does not set any attributes samples faces with such attributes will be skipped in a process of updating attributes with using new estimation algorithm.

required
Array of descriptor_data (object) or sdk_descriptor_base64 (string) (face_descriptors) [ 1 .. 1000 ] items

list of descriptors with different versions. Each descriptor was aggregated descriptor from the samples

face_descriptor_samples
Array of strings <uuid> (attributes_samples) [ 0 .. 1000 ] items unique
Default: []

list of uniqie sample ids which are resources for estimation attributes.

WARNING: if user does not set any attributes samples faces with such attributes will be skipped in a process of updating attributes with using new estimation algorithm.

Responses

Request samples

Content type
application/json
application/json
application/msgpack
Example
put face attribute specified by attribute data
put face attribute specified by attribute data
put face attribute specified by attribute id
{
  • "basic_attributes": {
    },
  • "basic_attributes_samples": [
    ],
  • "face_descriptors": [
    ],
  • "face_descriptor_samples": [
    ]
}

Response samples

Content type
application/json
Example
bad_json
bad_json
attribute_not_found
{
  • "error_code": 12022,
  • "desc": "Bad/incomplete input data",
  • "detail": "Failed to validate input json. Path: '', message: 'Additional properties are not allowed ('userdata' was unexpected)'"
}

get face attribute

Get face attribute by ID.

path Parameters
face_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

ID of the face (face_id received in the "create face" request).

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

targets
string <comma-separated items>
Default: "create_time,basic_attributes,basic_attributes_samples,face_descriptor,face_descriptor_samples"

list of comma-separated temporary attributes targets. Available targets: create_time, basic_attributes, basic_attributes_samples, face_descriptor, face_descriptor_samples

descriptor_version
integer (descriptor_version)
Enum: 46 52 54 56 57 58
Example: descriptor_version=56

descriptor version of the face descriptor attribute in response. By default used the platform defualt descriptor version.

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "attributes": {
    }
}

update face attribute

Update face attribute data: basic_attributes, basic_attributes_samples, face_descriptor, face_descriptor_samples.

path Parameters
face_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

ID of the face (face_id received in the "create face" request).

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Request Body schema: application/json
One of
required
object (basic_attributes)

basic attributes. Each basic attribute was aggregated from the samples. Samples is needed for re-extract attributes of new algorithm version and visualisation.

basic_attributes_samples
Array of strings <uuid> (attributes_samples) [ 0 .. 1000 ] items unique
Default: []

list of uniqie sample ids which are resources for estimation attributes.

WARNING: if user does not set any attributes samples faces with such attributes will be skipped in a process of updating attributes with using new estimation algorithm.

required
Array of descriptor_data (object) or sdk_descriptor_base64 (string) (face_descriptors) [ 1 .. 1000 ] items

list of descriptors with different versions. Each descriptor was aggregated descriptor from the samples

face_descriptor_samples
Array of strings <uuid> (attributes_samples) [ 0 .. 1000 ] items unique
Default: []

list of uniqie sample ids which are resources for estimation attributes.

WARNING: if user does not set any attributes samples faces with such attributes will be skipped in a process of updating attributes with using new estimation algorithm.

Responses

Request samples

Content type
application/json
Example
attribute_with_descriptors_and_basic_attributes_no_account
attribute_with_descriptors_and_basic_attributes_no_account
attribute_with_basic_attributes_no_account
attribute_with_descriptors_no_account
{
  • "basic_attributes": {
    },
  • "basic_attributes_samples": [
    ],
  • "face_descriptors": [
    ],
  • "face_descriptor_samples": [
    ]
}

Response samples

Content type
application/json
Example
bad_content_type
bad_content_type
bad_query_param
bad_json
non_unique_basic_attributes_samples
non_unique_face_descriptor_samples
attribute_for_update_not_found
sample_conflict
{
  • "error_code": 12017,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad content type"
}

delete face attribute

Remove face attribute by ID.

path Parameters
face_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

ID of the face (face_id received in the "create face" request).

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'account_id'"
}

get face attribute samples

Get face attribute samples by face ID.

path Parameters
face_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

ID of the face (face_id received in the "create face" request).

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "samples": [
    ]
}

temporary attributes

create a temporary attribute

Creating new temporary attributes. The attribute has a ttl and after an expire the time attribute will be removed from the service.

query Parameters
ttl
integer [ 1 .. 86400 ]
Default: 300

lifetime for temporary attribute (seconds)

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Content-Type
string
Enum: "application/json" "application/msgpack" "multipart/form-data"

Format of a request body data

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Request Body schema:
application/json
application/json
application/msgpack
multipart/form-data
One of
required
Array of descriptor_data (object) or sdk_descriptor_base64 (string) (face_descriptors) [ 1 .. 1000 ] items

list of descriptors with different versions. Each descriptor was aggregated descriptor from the samples

face_descriptor_samples
Array of strings <uuid> (attributes_samples) [ 0 .. 1000 ] items unique
Default: []

list of uniqie sample ids which are resources for estimation attributes.

WARNING: if user does not set any attributes samples faces with such attributes will be skipped in a process of updating attributes with using new estimation algorithm.

account_id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

id of the luna account.

required
object (basic_attributes)

basic attributes. Each basic attribute was aggregated from the samples. Samples is needed for re-extract attributes of new algorithm version and visualisation.

basic_attributes_samples
Array of strings <uuid> (attributes_samples) [ 0 .. 1000 ] items unique
Default: []

list of uniqie sample ids which are resources for estimation attributes.

WARNING: if user does not set any attributes samples faces with such attributes will be skipped in a process of updating attributes with using new estimation algorithm.

Responses

Request samples

Content type
application/json
application/json
application/msgpack
multipart/form-data
Example
attribute_with_descriptors_and_basic_attributes
attribute_with_descriptors_and_basic_attributes
attribute_with_descriptors
attribute_with_basic_attributes
{
  • "face_descriptors": [
    ],
  • "face_descriptor_samples": [
    ],
  • "account_id": "557d54ec-29ad-4f3c-93b4-c9092ef12515",
  • "basic_attributes": {
    },
  • "basic_attributes_samples": [
    ]
}

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "attribute_id": "b5d6fd45-fcca-453d-ac05-3e594054b813",
  • "url": "/3/attributes/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

get temporary attributes

get temporary attribute by ids.

query Parameters
attribute_ids
required
string <list of uuid>

list of comma-separated attribute ids.

account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

targets
string <comma-separated items>
Default: "basic_attributes"
Example: targets=basic_attributes,basic_attributes_samples,account_id

list of comma-separated temporary attributes targets. Available targets: face_descriptor, basic_attributes, basic_attributes_samples, face_descriptor_samples, account_id, create_time, attribute_id

descriptor_version
integer (descriptor_version)
Enum: 46 52 54 56 57 58
Example: descriptor_version=56

descriptor version of the face descriptor attribute in response. By default used the platform defualt descriptor version.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Accept
string
Enum: "application/json" "application/msgpack"

Which content-type is requested. application/json by default

Responses

Response samples

Content type
application/json
application/json
application/msgpack
Example
default
default
full
{
  • "attributes": [
    ]
}

get temporary attributes count

get temporary attributes count

WARNING: there is no ability to get attribute count by accounts

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "attributes_count": 146
}

put temporary attribute

Put temporary attribute by id.

path Parameters
attribute_id
required
string <uuid> (attribute_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

id of the temporary attribute.

query Parameters
ttl
integer [ 1 .. 86400 ]
Default: 300

lifetime for temporary attribute (seconds)

force
integer
Default: 0
Enum: 0 1

replace an attribute if there exist attribute with same attribute_id. If parameter is equal to 0 and attribute with same attribute_id is exists the request will be failed.

header Parameters
Content-Type
string
Enum: "application/json" "multipart/form-data" "application/msgpack"

Format of a request body data

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Request Body schema:
application/json
application/json
application/msgpack
multipart/form-data
One of
required
Array of descriptor_data (object) or sdk_descriptor_base64 (string) (face_descriptors) [ 1 .. 1000 ] items

list of descriptors with different versions. Each descriptor was aggregated descriptor from the samples

face_descriptor_samples
Array of strings <uuid> (attributes_samples) [ 0 .. 1000 ] items unique
Default: []

list of uniqie sample ids which are resources for estimation attributes.

WARNING: if user does not set any attributes samples faces with such attributes will be skipped in a process of updating attributes with using new estimation algorithm.

account_id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

id of the luna account.

required
object (basic_attributes)

basic attributes. Each basic attribute was aggregated from the samples. Samples is needed for re-extract attributes of new algorithm version and visualisation.

basic_attributes_samples
Array of strings <uuid> (attributes_samples) [ 0 .. 1000 ] items unique
Default: []

list of uniqie sample ids which are resources for estimation attributes.

WARNING: if user does not set any attributes samples faces with such attributes will be skipped in a process of updating attributes with using new estimation algorithm.

Responses

Request samples

Content type
application/json
application/json
application/msgpack
multipart/form-data
Example
attribute_with_descriptors_and_basic_attributes
attribute_with_descriptors_and_basic_attributes
attribute_with_descriptors
attribute_with_basic_attributes
{
  • "face_descriptors": [
    ],
  • "face_descriptor_samples": [
    ],
  • "account_id": "557d54ec-29ad-4f3c-93b4-c9092ef12515",
  • "basic_attributes": {
    },
  • "basic_attributes_samples": [
    ]
}

Response samples

Content type
application/json
Example
bad_query_param
bad_query_param
bad_json
broken_descriptor
broken_xpk
unknown_descriptor_version
xpk_withot_descriptor
not_valid_sdk_descriptor
unknown_multimart_name
duplicate_multipart_name
bad_multipart_content_type
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'force'"
}

get temporary attribute

get temporary attribute by id.

path Parameters
attribute_id
required
string <uuid> (attribute_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

id of the temporary attribute.

query Parameters
descriptor_version
integer (descriptor_version)
Enum: 46 52 54 56 57 58
Example: descriptor_version=56

descriptor version of the face descriptor attribute in response. By default used the platform defualt descriptor version.

account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

targets
string <comma-separated items>
Default: "basic_attributes"
Example: targets=basic_attributes,basic_attributes_samples,account_id

list of comma-separated temporary attributes targets. Available targets: face_descriptor, basic_attributes, basic_attributes_samples, face_descriptor_samples, account_id, create_time, attribute_id

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Accept
string
Enum: "application/json" "application/msgpack"

Which content-type is requested. application/json by default

Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Responses

Response samples

Content type
application/msgpack
application/msgpack
application/json
No sample

check temporary attribute

check temporary attribute existence.

path Parameters
attribute_id
required
string <uuid> (attribute_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

id of the temporary attribute.

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

delete attribute

delete the attribute by its id.

path Parameters
attribute_id
required
string <uuid> (attribute_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

id of the temporary attribute.

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'account_id'"
}

get temporary attribute samples

get all the temporary attribute samples by the attribute ID.

path Parameters
attribute_id
required
string <uuid> (attribute_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

id of the temporary attribute.

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "samples": [
    ]
}

descriptors_caching

get face descriptor batches

Get face descriptors using face ids or list id with filters. Returns requested descriptors as SDKData object

query Parameters
check_existence
integer
Enum: 0 1

whether to check requested objects' existense

parity
integer
Enum: 0 1

keys' parity: 0 for even keys in batch and 1 for odd keys, parity filter is not used if not set

receive_external_id
integer
Enum: 0 1

whether to return external ids in the response

header Parameters
Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Request Body schema:
application/json
application/json
application/msgpack
One of
face_ids
required
Array of strings <uuid> (face_id) <= 1000 items

face ids of faces whose descriptors should be obtained

Responses

Request samples

Content type
application/json
application/json
application/msgpack
Example
post_attributes_batches_faces
post_attributes_batches_faces
post_attributes_batches_list
{
  • "face_ids": [
    ]
}

Response samples

Content type
application/json
Example
bad_query_param
bad_query_param
list_not_found
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'parity'"
}

get list attributes

Get list attributes' link keys

path Parameters
list_id
required
string <uuid> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

list id (list_id received in the "create list" response)

query Parameters
link_key__lt
integer (link_key) >= 0

the upper excluding link_key boundary

link_key__gte
integer (link_key) >= 0

the lower including link_key boundary

limit
integer (limit) >= 1

the maximum count of results in the reply

parity
integer
Enum: 0 1

keys' parity: 0 for even keys in batch and 1 for odd keys, parity filter is not used if not set

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Responses

Response samples

Content type
application/json
application/json
application/msgpack
[
  • {
    }
]

get unlinked attributes

Get ids and link and unlink keys for each unlinked attribute.

path Parameters
list_id
required
string <uuid> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

list id (list_id received in the "create list" response)

query Parameters
link_key__lt
integer (unlink_key) >= 0

the upper excluding unlink_key boundary

link_key__gte
integer (unlink_key) >= 0

the lower including unlink_key boundary

limit
integer (limit) >= 1

the maximum count of results in the reply

parity
integer
Enum: 0 1

keys' parity: 0 for even keys in batch and 1 for odd keys, parity filter is not used if not set

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Responses

Response samples

Content type
application/json
application/json
application/msgpack
[
  • {
    }
]

get lists' link and unlink keys

Get lists with link and unlink keys grouped by list ids

query Parameters
use_parity
integer
Enum: 0 1

link/unlink keys' parity - if 0 get max link/unlink keys, if 1 get max even and odd link/unlink keys separetely

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Request Body schema:
application/json
application/json
application/msgpack
list_ids
required
Array of strings <uuid> (list_id) <= 1000 items

target list ids to get max link/unlink keys info

Responses

Request samples

Content type
application/json
application/json
application/msgpack
{
  • "list_ids": [
    ]
}

Response samples

Content type
application/json
application/json
application/msgpack
Example
post_linkkeys_reply_no_parity
post_linkkeys_reply_no_parity
post_linkkeys_reply_parity
{
  • "lists": [
    ]
}

lists

create a list

Creating new list.

query Parameters
list_id
string <uuid> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: list_id=557d54ec-29ad-4f3c-93b4-c9092ef12515

id of a list that contains faces.

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Request Body schema:
application/json
application/json
application/msgpack
account_id
required
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

id of the luna account.

user_data
string (user_data) <= 128 characters
Default: ""

user data.

Responses

Request samples

Content type
application/json
application/json
application/msgpack
{
  • "account_id": "0468ca85-f6ca-4841-b30c-5ccc26b6f397",
  • "user_data": "100-00-12"
}

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "list_id": "b5d6fd45-fcca-453d-ac05-3e594054b813",
  • "url": "/2/lists/b5d6fd45-fcca-453d-ac05-3e594054b813"
}

get lists

get lists by filters.

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

user_data
string
Example: user_data=user_data_text

find all objects with user_data that is similar to this parameter. You can specify some part of the user_data value for this filter.

user_data__eq
string
Example: user_data__eq=user_data_text

find all objects with same user_data.

create_time__lt
string <date-time> (time)
Example: create_time__lt=2018-08-11T09:11:41.674Z

upper bound for object create_time.

create_time__gte
string <date-time> (time)
Example: create_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object create_time.

last_update_time__lt
string <date-time> (time)
Example: last_update_time__lt=2018-08-11T09:11:41.674Z

upper bound for object create_time.

last_update_time__gte
string <date-time> (time)
Example: last_update_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object create_time.

list_ids
string <list of uuid>

list of comma-separated list ids.

list_id__lt
string <uuid>

upper list id excluding boundary.

list_id__gte
string <uuid>

lower list id including boundary.

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "lists": [
    ]
}

delete lists

Delete several lists.

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

with_faces
integer
Default: 0
Enum: 0 1

whether to delete list with all its' faces

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Request Body schema:
application/json
application/json
application/msgpack
list_ids
required
Array of strings <uuid> (list_id) [ 1 .. 1000 ] items

ids of list for removal

Responses

Request samples

Content type
application/json
application/json
application/msgpack
{
  • "list_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "error_code": 12022,
  • "desc": "Bad/incomplete input data",
  • "detail": "Failed to validate input json. Path: '', message: 'Additional properties are not allowed ('faces' was unexpected)'"
}

get lists count

get lists count

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

user_data
string
Example: user_data=user_data_text

find all objects with user_data that is similar to this parameter. You can specify some part of the user_data value for this filter.

user_data__eq
string
Example: user_data__eq=user_data_text

find all objects with same user_data.

create_time__lt
string <date-time> (time)
Example: create_time__lt=2018-08-11T09:11:41.674Z

upper bound for object create_time.

create_time__gte
string <date-time> (time)
Example: create_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object create_time.

last_update_time__lt
string <date-time> (time)
Example: last_update_time__lt=2018-08-11T09:11:41.674Z

upper bound for object create_time.

last_update_time__gte
string <date-time> (time)
Example: last_update_time__gte=2018-08-11T09:11:41.674Z

lower included bound for object create_time.

list_ids
string <list of uuid>

list of comma-separated list ids.

list_id__lt
string <uuid>

upper list id excluding boundary.

list_id__gte
string <uuid>

lower list id including boundary.

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "lists_count": 146
}

get list

Get list by id

path Parameters
list_id
required
string <uuid> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

list id (list_id received in the "create list" response)

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "account_id": "0468ca85-f6ca-4841-b30c-5ccc26b6f397",
  • "list_id": "429b0e78-4616-426a-b57f-02baa72d638d",
  • "user_data": "string",
  • "create_time": "string",
  • "last_update_time": "string"
}

check list existence

Check existence of the list with id=list_id.

path Parameters
list_id
required
string <uuid> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

list id (list_id received in the "create list" response)

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error",
  • "desc": "internal server error"
}

update list

Update the user_data field of the list.

path Parameters
list_id
required
string <uuid> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

list id (list_id received in the "create list" response)

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Request Body schema:
application/json
application/json
application/msgpack
user_data
required
string <= 128 characters

user data.

Responses

Request samples

Content type
application/json
application/json
application/msgpack
{
  • "user_data": "string"
}

Response samples

Content type
application/json
Example
bad_content_type
bad_content_type
bad_json
{
  • "error_code": 12017,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad content type"
}

remove list

Remove list by id

path Parameters
list_id
required
string <uuid> (list_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

list id (list_id received in the "create list" response)

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

with_faces
integer
Default: 0
Enum: 0 1

whether to delete list with all its' faces

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 22003,
  • "desc": "Object not found",
  • "detail": "List with id '7acc35cf-a3b2-4f87-8d8b-5496a2782d37' not found"
}

administration

get lists deletions

Get a log of deleted lists. The method is intended for auditing and tracking deleted lists.

query Parameters
deletion_time__lt
string <date-time> (time)
Example: deletion_time__lt=2018-08-11T09:11:41.674Z

upper bound for list deletion time.

deletion_time__gte
string <date-time> (time)
Example: deletion_time__gte=2018-08-11T09:11:41.674Z

lower included bound for list deletion time.

page
integer >= 1
Default: 1

a page number.

page_size
integer [ 1 .. 100 ]
Default: 10

the number of items on page.

Responses

Response samples

Content type
application/json
{
  • "removed_lists": [
    ]
}

clear lists deletions log

Clear lists deletions log. It is not recommended to remove all the records from the log. Save last-day records for correct operation of third-party caching mechanisms (matcher).

query Parameters
deletion_time__lt
required
string <date-time> (time)
Example: deletion_time__lt=2018-08-11T09:11:41.674Z

upper bound for list deletion time.

Responses

Response samples

Content type
application/json
Example
bad_query_param
bad_query_param
without_time
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'deletion_time__lt'"
}

get faces without descriptor

Get faces:

  1. without descriptors of the missing_version
  2. with descriptor of a default version
  3. with samples
query Parameters
missing_version
required
integer

a face descriptor of this version must be missing

account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

face_id__lt
string <uuid>

upper face id excluding boundary.

face_id__gte
string <uuid>

lower face id including boundary.

limit
integer (missing_limit) [ 1 .. 1000 ]

the maximum count of faces in the reply

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Request Body schema:
application/json
application/json
application/msgpack
face_ids
required
Array of strings <uuid> (face_id) [ 1 .. 1000 ] items

ids of faces for search

Responses

Request samples

Content type
application/json
application/json
application/msgpack
{
  • "face_ids": [
    ]
}

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "faces": [
    ]
}

get face count without descriptor

Get face without descriptrs input version count and with descriptor of a default version

query Parameters
missing_version
required
integer

a face descriptor of this version must be missing

account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

face_id__lt
string <uuid>

upper face id excluding boundary.

face_id__gte
string <uuid>

lower face id including boundary.

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Request Body schema:
application/json
application/json
application/msgpack
face_ids
required
Array of strings <uuid> (face_id) [ 1 .. 1000 ] items

ids of faces for search

Responses

Request samples

Content type
application/json
application/json
application/msgpack
{
  • "face_ids": [
    ]
}

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "faces_count": 146
}

get descriptor count info

Get information of the count of descriptors of available versions

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "descriptor_count_info": [
    ]
}

get faces without basic attributes

Get faces that do not have basic attributes.

The response will include face IDs and their samples. If a face has no samples, the array of samples will be empty.

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

face_id__lt
string <uuid>

upper face id excluding boundary.

face_id__gte
string <uuid>

lower face id including boundary.

limit
integer (missing_limit) [ 1 .. 1000 ]

the maximum count of faces in the reply

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Request Body schema:
application/json
application/json
application/msgpack
face_ids
required
Array of strings <uuid> (face_id) [ 1 .. 1000 ] items

ids of faces for search

Responses

Request samples

Content type
application/json
application/json
application/msgpack
{
  • "face_ids": [
    ]
}

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "faces": [
    ]
}

get face count without basic attributes

Count faces without basic attributes.

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

face_id__lt
string <uuid>

upper face id excluding boundary.

face_id__gte
string <uuid>

lower face id including boundary.

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Request Body schema:
application/json
application/json
application/msgpack
face_ids
required
Array of strings <uuid> (face_id) [ 1 .. 1000 ] items

ids of faces for search

Responses

Request samples

Content type
application/json
application/json
application/msgpack
{
  • "face_ids": [
    ]
}

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "faces_count": 146
}

get basic attributes count info

Сount basic attributes saved to the Faces database.

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "basic_attributes_count": 0
}

delete face descriptors by version

Delete face descriptors by version

path Parameters
version
required
integer

descriptor version for deletion

query Parameters
face_id__lt
string <uuid>

upper face id excluding boundary.

face_id__gte
string <uuid>

lower face id including boundary.

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Responses

Response samples

Content type
application/json
application/json
application/msgpack
{
  • "face_ids": [
    ]
}

linker

link (or unlink) faces to a list

link (or unlink) faces to a list

query Parameters
account_id
string <uuid> (account_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

luna account id

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header. Depends on Accept header in the request.

Request Body schema:
application/json
application/json
application/msgpack
action
required
string
Enum: "attach" "detach"

action to perform: attach faces to list or detach

face_ids
required
Array of strings <uuid> (uuid) <= 1000 items

face ids

list_id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

list id

Responses

Request samples

Content type
application/json
application/json
application/msgpack
{
  • "action": "attach",
  • "face_ids": [
    ],
  • "list_id": "string"
}

Response samples

Content type
application/json
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'account_id'"
}

Clean unlink log

Clean history of unlink attributes from lists. This history is required for correct update cash in matchers.

query Parameters
time__lt
string <date-time> (time)
Example: time__lt=2018-08-11T09:11:41.674Z

Upper bound of log time with timezone excluding boundary. This time should be less than now minus last matcher cache update period; otherwise one should drop matchers' caches after performing this request: otherwise some removed faces can be found in match candidates.

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 12012,
  • "desc": "Bad/incomplete input data",
  • "detail": "Bad query parameters 'time__lt'"
}

documents

get openapi documentation

Get service OpenApi documentation. If Accept request header is of type application/x-yaml, returns documentation in yaml format or returns html documentation, if Accept-Type is text/html

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Accept
required
string (accept_docs_handler)
Enum: "application/x-yaml" "text/html"

acceptable type of receiving data

Responses

Response samples

Content type
application/json
{
  • "error_code": 12024,
  • "detail": "Bad/incomplete input data",
  • "desc": "Unsupported media type"
}

get development manual

Get sphinx documentation - Development Manual. After the request you will be redirected to the page /docs/dev/index.html

header Parameters
Accept
string
Enum: "application/json" "application/msgpack"

Preferred response content type

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "error_code": 1,
  • "detail": "internal server error",
  • "desc": "internal server error"
}