Create a data source

Purpose

A data source is a named origin of images in your account. Its settings decide which features are detected on every image of the source, when a new person is created automatically, and to which person lists. Images you send for the source are attributed to it through group_id and source_id.

Request

POST <API_BASE_URL>/source/create. All calls are POST under your API address. Replace <API_BASE_URL> with the API address provided with your access.

Send a permanent API token in the token field of the body, or a user token in the token header. See authentication.

Content type: application/json.

Field	Type	Required	Description
`token`	string (uuid)	if no header	Your permanent API token. Required unless you send a user token in the `token` header.
`group_id`	string	yes	The group the source belongs to.
`name`	string	yes	The name of the new source.
`feature_check`	array of object or string	no	Features to detect on every image of the source: a name or an array of names such as `age`, `gender`, `mood`, `glasses` or `mask`.
`new_person_threshold`	value	no	The match threshold below which a new person is created automatically. The value `never` creates no person; `no_match` uses the platform default, which is recommended.
`new_person_square_min`	value	no	The smallest face side, in pixels, from which a person is created automatically.
`new_person_yaw_max`	value	no	The largest left or right rotation, in degrees, at which a person is created automatically.
`new_person_pitch_max`	value	no	The largest up or down tilt, in degrees, at which a person is created automatically.
`person_list_add`	array of string (uuid)	no	An array of person list identifiers. Persons created automatically are added to each of them.
`person_list_search`	array of object	no	One or more person lists in which to search for matches. Each item holds a list identifier and alert messages.

Response

HTTP 201. The source was created in the group.

Field	Type	Description
`status`	string	Always `ok` on this body.
`source_id`	string (uuid)	The identifier of the source just created.

Errors

400: The body failed validation. The answer has status of error and a details list with one entry per offending field (path, expected, actual).
401: The token is missing, expired or unknown.

A refusal can also come before the operation runs: an address outside your IP allowlist, a token bound to another address, or a body that is not valid JSON. See response format and errors.

Example

Request:

curl -X POST "<API_BASE_URL>/source/create" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<your permanent API token>",
    "group_id": "<group id>",
    "name": "Front door",
    "new_person_threshold": "no_match",
    "person_list_add": [
      "<person list id>"
    ]
  }'

Response:

{
  "status": "ok",
  "source_id": "<source id>"
}