Faces API

Base URL: https://YOUR-SERVER/api. Send your API key in x-api-key where authentication is required. A key also needs the listed permission; your account's access rules still apply.

API guide · All endpoints · OpenAPI JSON

• GET /faces — Retrieve faces for asset
• POST /faces — Create a face
• GET /faces/source — Retrieve the face source revision for an asset
• DELETE /faces/{id} — Delete a face
• PATCH /faces/{id} — Correct a face
• PUT /faces/{id} — Re-assign a face to another person

Retrieve faces for asset

GET /api/faces

Retrieve all faces belonging to an asset.

Authentication: API key. Permission: face.read.

Parameters

Name	Where	Required	Description
id	query	Yes	Face ID
withHidden	query	No	Also list faces the asset's owner hid (owner only)

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "query",
    "description": "Face ID",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  },
  {
    "name": "withHidden",
    "required": false,
    "in": "query",
    "description": "Also list faces the asset's owner hid (owner only)",
    "schema": {
      "type": "boolean"
    }
  }
]

Responses

Field definitions: AssetFaceResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/AssetFaceResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Create a face

POST /api/faces

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

Authentication: API key. Permission: face.create.

Request body

Required.

Field definitions: AssetFaceCreateDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AssetFaceCreateDto"
    }
  }
}

Responses

Field definitions: AssetFaceResponseDto

{
  "201": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AssetFaceResponseDto"
        }
      }
    },
    "description": ""
  }
}

Retrieve the face source revision for an asset

GET /api/faces/source

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

Authentication: API key. Permission: face.read.

Parameters

Name	Where	Required	Description
id	query	Yes	Face ID

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "query",
    "description": "Face ID",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Responses

Field definitions: AssetFaceSourceResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AssetFaceSourceResponseDto"
        }
      }
    },
    "description": ""
  }
}

Delete a face

DELETE /api/faces/{id}

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

Authentication: API key. Permission: face.delete.

Parameters

Name	Where	Required	Description
id	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: AssetFaceDeleteDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AssetFaceDeleteDto"
    }
  }
}

Responses

{
  "204": {
    "description": ""
  }
}

Correct a face

PATCH /api/faces/{id}

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

Authentication: API key. Permission: face.update.

Parameters

Name	Where	Required	Description
id	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: AssetFaceCorrectionDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AssetFaceCorrectionDto"
    }
  }
}

Responses

Field definitions: AssetFaceResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AssetFaceResponseDto"
        }
      }
    },
    "description": ""
  }
}

Re-assign a face to another person

PUT /api/faces/{id}

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

Authentication: API key. Permission: face.update.

Parameters

Name	Where	Required	Description
id	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "name": "id",
    "required": true,
    "in": "path",
    "schema": {
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
      "type": "string"
    }
  }
]

Request body

Required.

Field definitions: FaceDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/FaceDto"
    }
  }
}

Responses

Field definitions: PersonResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PersonResponseDto"
        }
      }
    },
    "description": ""
  }
}