Videntifier API Reference

Videntifier provides a RESTful HTTP API for inserting, querying and managing your image and video content.

Authentication

Videntifier API requires SSL. You must have a valid API token to make API requests. To authenticate a request, you should include the API token in the Authorization header.

All example requests in this documentation set the following HTTP header:

`Authorization: tw3v2Ep1K94ohFZPHQPX`

On signup, you will be provided with an API token.

Requests

The Videntifier API is a RESTful JSON API. Successful requests set the Content-Type header to application/json, but in case of an error (such as a bad request), you may get a text/plain response header.

If you submit a POST or PUT request you must set the Content-Type to multipart/form-data.

Database hostname

Most endpoints in this documentation show examples of how to call the API using curl. As the actual hostname can change between clients, we refer to host as the hostname of the database.

https://host.videntifier.com/api/v1/

On signup, you will be provided with the hostname.

Response Format

The Videntifier API uses HTTP status codes to indicate success or failure. A 2xx status code indicates success. A 4xx status code indicates an error with the request. A 5xx status indicates a failure on the server side.

Code	Status
200	Success
303	Resource created elsewhere
400	Bad request
401	Authorization error
404	Not found
409	Conflict
500	Internal server error

In case of a 400/5xx error, you will get an application/json response that describes the error.

Example:

{
    "error": {
        "code": "400",
        "message": "Invalid query parameter"
    }
}

Pagination

Most list endpoints support pagination. You can change the number of records returned and which page to return by specifying the following parameters:

• page: Which page to return.
• page_size: How many records to list per page. By default, 50 records are returned. The maximum allowed value for this field is 100.

Pagination information is included in a _metadata value in the JSON response:

"_metadata": {
    "page": "1",
    "page_size": "50",
    "nr_pages": "20",
    "nr_results": "995",
    "links": {
        "self": "https://host.videntifier.com/api/v1/contents&page=1",
        "next": "https://host.videntifier.com/api/v1/contents&page=2",
        "prev": null,
        "first": "https://host.videntifier.com/api/v1/contents",
        "last": "https://host.videntifier.com/api/v1/contents&page=995"
    }
}

API Endpoints Overview

URL	HTTP Method	Description
/account	GET	Get account info
/profiles	GET	List profiles
/query	POST	Query an image or video
/query_async	POST	Query an image or video asynchronously
/query_results	GET	Retrieve a persisted query result
/query_sw	POST	Query a video in a "source within" mode
/query_sw_async	POST	Query a video in a "source within" mode asynchronously
/query_results_sw	GET	Retrieve a persisted "source within" query result
/insert	POST	Insert an image or video
/insert_async	POST	Insert an image or video asynchronously
/jobs	GET	List jobs
/jobs/:id	GET	Get job status
/jobs/:id	DELETE	Delete a job status
/contents	GET	List inserted images and videos
/contents/:id	GET	Get info about an image or video
/contents/:id	DELETE	Delete an image or video
/contents/:id/metadata	PUT	Update metadata
/users	GET	List users
/users	POST	Create user
/users/:id	PATCH	Update user information
/users/:id	DELETE	Delete user
/users/:id	GET	Get info about user
/dbinfo	GET	Get info about database

Get account info

Endpoint

GET /account

Required Parameters

None

Optional Parameters

None

Response

The response shows details about your account, including how much content you have inserted into the database. The following fields are always present in the response:

• organization: The name of your organization.
• nr_points: How many visual points all users from your organization have inserted into the database.
• max_points: The maximum number of visual points all users from your organization can insert. If this limit is reached, you might get an error when inserting new content. If set to 0, there is no limit.
• nr_images: How many images all users from your organization have inserted into the database.
• nr_videos: How many videos all users from your organization have inserted into the database.
• nr_video_seconds: How many seconds of video content all users from your organization have inserted into the database.
• users: Shows the username of each user in the organization along with how much content each user has inserted into the database.

Example request:

curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     'https://host.videntifier.com/api/v1/account'

Example response:

{
    "data": {
        "account": {
            "organization": "videntifier",

            "nr_points": "34627",
            "nr_images": "54",
            "nr_videos": "2",
            "nr_video_seconds": "262",
            "max_points": "100000",

            "users": [
                {
                    "username": "user1",
                    "nr_images": "54",
                    "nr_videos": "2",
                    "nr_video_seconds": "262",
                    "nr_points": "34627"
                }
            ]
        }
    }
}

List profiles

Endpoint

GET /profiles

Required Parameters

None

Optional Parameters

None

Response

The response lists all available profiles. A profile can be chosen per request when querying or inserting into the database. Currently, profiles only affect the signature extraction, but in later versions, profiles might be extended to affect other parameters.

Depending on the use case, we want to be able to tune the extraction settings based on whether we are querying or inserting an image or video. To support this, each profile defines the following parameters:

• image_query: The extraction settings when querying an image.
• image_insert: The extraction settings when inserting an image.
• video_query: The extraction settings when querying a video.
• video_insert: The extraction settings when inserting a video.

Example request:

curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     'https://host.videntifier.com/api/v1/profiles'

Example response:

{
    "data": {
        "profiles": [
            {
                "name": "hq",
                "description": "High quality extraction mode",
                "extraction": {
                    "image_query": "",
                    "image_insert": "--high-quality",
                    "video_query": "",
                    "video_insert": "--high-quality"
                }
            },
            {
                "name": "hq-sw",
                "description": "Optimized extraction mode for source-within",
                "extraction": {
                    "image_query": "",
                    "image_insert": "--high-quality",
                    "video_query": "",
                    "video_insert": "--high-quality --scene-mode=REALTIME --scene-max-duration=10"
                }
            }
        ]
    }
}

Query an image or video

Endpoint

POST /query

Required Parameters

The /query endpoint supports multiple ways to query a content. If the content is already in the database, you can query it by its content_id. You can also provide a download_url that instructs the database to first download the content and then query it. You can also upload the content or its signature directly by writing it to the form file.

To query, you must provide one of the parameters:

• content_id (form-field): The contentID of the image or video you want to query.
• download_url (form-field): A valid URL where the image or video you want to query can be downloaded from.
• file (form-field): A local file on your machine that you will upload to the database for querying (file can be an image, video or .desc72 signature).

Note

If more than one parameter is specified, you will receive an HTTP Bad Request error.

Optional Parameters

• profile: The profile you want to use for the query. Note that if the signature was already computed (e. query by content_id or uploaded as desc72), the profile is ignored.
• include_locations: If set to true, the query response will include an array of locations showing detailed match information about all matching content.
• include_query_stats: If set to true, the query response will include statistics about the query, including how much time each part of the query took.
• include_points: If set to true, each match location will include an array of visual point coordinates in string format "x_query,y_query,x_match,y_match". The match will also include bounding boxes that encompass all matching descriptors in both the query and match scenes. This option is only available if the query includes locations. Currently this feature is only supported for images.

Response

At the root of the JSON query response, the following fields are present:

• query: JSON object with information about performed query. It has the following fields:
  • id: Query response is persisted and can be retrieved at a later time using query result id. Persisted result expires after some time, for details see Retrieve a persisted query result
  • type: Type of the content queried. Can be 'video' or 'image'.
  • download_url: This field is present in the response if the query was performed using URL. It contains the queried URL.
  • content: This object contains information about the queried object (for field description see Get info about an image or video)
  • content_id: This field is present in the response if the query was performed using content id and it contains content id that was used in the query.
  • file: This field is present in the response if the query was performed using file upload. It contains the filename of the file used.
• visualization_url: URL to the visual user interface where query results can be examined in a browser.
• _metadata: Pagination information.
• query_stats: Query statistics.
• matches: An array of matches, where each match has the following fields:
  • content: The content that is matching. For field description see Get info about an image or video
  • coverage: A percentage of the query video matching to the match or null if the query media type is an image.
  • match_type: Whether the match is a similarity match or a visual copy.
  • nr_matching_points: How many points in the query are matching this match.
  • locations: If the include_locations query param is set to true, then each match will also include a list of matching locations between the query and match. This is only relevant for videos. Each location has the following fields:
    • query_locations: An array of query locations matching at this location. If the query is an image this will always be an empty array.
    • match_locations: An array of match locations matching at this location. If the match is an image this will always be an empty array.
    • query_perc: A percentage of the area in the query that is matching at this location(between 0-100%).
    • match_perc: A percentage of the area in the match that is matching at this location (between 0-100%).
    • scene_id: The scene_id of the match that was matching at this location.
    • visual_copy: Set to true if both query_perc and match_perc are above 85, indicating that the result is an exact match. Note that an image can be considered a visual copy even though it has been modified to some extent (mirrored or rotated, for example).
• related_matches: For accounts where this functionality is enabled, the query will perform a more extensive search. In addition to direct matches, the query result will also contain an array of related matches. Related matches are indirectly related to queried content. For details, see [Related matches][#related-matches]

Example request:

To query a file by providing download_url:

curl -X POST \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     -F 'download_url=URL' \
     'https://host.videntifier.com/api/v1/query'

To query a local file:

curl -X POST \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     -F 'file=@/path/to/file' \
     'https://host.videntifier.com/api/v1/query?include_locations=true&include_points=true'

Example response

{
    "data": {
        "query": {
            "content": {
                "content_id": "996",
                "created_at": "2018-01-10T05:51:03.658786Z",
                "duration": null,
                "file_size": "799450",
                "filename": "image.jpeg",
                "insert_method": "content",
                "metadata": {},
                "nr_points": "303",
                "scaled_height": "360",
                "scaled_width": "240",
                "sha1sum": "1f914ad2c9d7bbcbd399ff450ad21e290951d537",
                "type": "image",
                "url": "https://localhost:9000/data/1f914ad2c9d7bbcbd399ff450ad21e290951d537.png",
                "username": "user1"
            },
            "content_id": "996",
            "id": "1",
            "type": "image"
        },
        "matches": [
            {
                "content": {
                    "content_id": "997",
                    "created_at": "2017-10-11T09:22:44.566794Z",
                    "duration": null,
                    "file_size": "100495",
                    "filename": "image.jpg",
                    "insert_method": "content",
                    "metadata": {},
                    "nr_points": "531",
                    "scaled_height": "360",
                    "scaled_width": "240",
                    "sha1sum": "3bbbb3248dc4e727545ef1835462ae9954b141ad",
                    "type": "image",
                    "url": "https://host.videntifier.com/data/3bbbb3248dc4e727545ef1835462ae9954b141ad.jpg",
                    "username": "user1"
                },
                "coverage": null,
                "locations": [
                    {
                        "match_locations": [],
                        "match_perc": "100.00",
                        "query_locations": [],
                        "query_perc": "100.00",
                        "scene_id": "997",
                        "visual_copy": true,
                        "bounding_boxes": {
                            "match": {
                                "max_x": "367",
                                "min_x": "0",
                                "max_y": "197",
                                "min_y": "0"
                            },
                            "query": {
                                "max_x": "367",
                                "min_x": "0",
                                "max_y": "197",
                                "min_y": "0"
                            }
                        },
                        "points": [
                            "289,68,289,68",
                            "336,54,336,54",
                            "136,42,136,42",
                        ]
                    }
                ],
                "match_type": "visual_copy",
                "nr_matching_points": "443"
            }
        ],
        "query_stats": {
            "nr_frames_queried": "3",
            "nr_points_queried": "1463",
            "time_fetch_points": "14ms",
            "time_init_matching": "2ms",
            "time_matching": "9ms",
            "time_query": "26ms",
            "time_total_ms": "107ms"
        },
        "related_matches": [
            {
                "content": {
                    "content_id": "1011",
                    "created_at": "2018-02-12T18:07:10.513584Z",
                    "duration": null,
                    "file_size": "425377",
                    "filename": "image2.png",
                    "insert_method": "content",
                    "metadata": {},
                    "nr_points": "1005",
                    "scaled_height": "512",
                    "scaled_width": "512",
                    "sha1sum": "28bd1cdf0df08477c65b1749ef2f8426d16c149c",
                    "type": "image",
                    "url": "https://localhost:9000/data/28bd1cdf0df08477c65b1749ef2f8426d16c149c.png",
                    "username": "user2"
                },
                "locations": [
                    {
                        "match_locations": [],
                        "match_perc": "100.00",
                        "query_locations": [],
                        "query_perc": "100.00",
                        "scene_id": "1011",
                        "visual_copy": true,
                        "bounding_boxes": {
                            "match": {
                                "max_x": "367",
                                "min_x": "0",
                                "max_y": "197",
                                "min_y": "0"
                            },
                            "query": {
                                "max_x": "367",
                                "min_x": "0",
                                "max_y": "197",
                                "min_y": "0"
                            }
                        },
                        "points": [
                            "289,68,289,68",
                            "336,54,336,54",
                            "136,42,136,42",
                        ]
                    }
                ],
                "related_content_id": "997",
                "related_depth": "1"
            }
        ],
        "_metadata": {
            "links": {
                "first": "https://host.videntifier.com/api/v1/query_results/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&include_locations=true&page=1&page_size=50",
                "last": "https://host.videntifier.com/api/v1/query_results/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&include_locations=true&page=1&page_size=50",
                "next": null,
                "prev": null,
                "self": "https://host.videntifier.com/api/v1/query_results/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&include_locations=true&page=1&page_size=50"
            },
            "nr_pages": "1",
            "nr_results": "1",
            "page": "1",
            "page_size": "50"
        },
        "visualization_url": "https://ui.videntifier.com/api/v1/query_results/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD"
    }
}

Retrieve a persisted query result

Endpoint

GET /query_results/:id

Required Parameters

• access_token: Access token, provided as part of query_result_url from the original query response.

Optional Parameters

• page: Which page to return.
• page_size: How many records to list per page. By default 50 records are returned. The maximum allowed value for this field is 100.
• filter_attr: Attribute used to filter the list of matches. Any of the attributes in match content information can be used as a filter field, as well as coverage, match_type and nr_matching_points. This attribute is not set by default.
• filter: Value applied to filter attribute. This attribute is not set by default.
• sort_attr: Attribute used to sort the list of matches. Any of the attributes in match content information can be used as a filter field, as well as coverage, match_type and nr_matching_points. The default value for this attribute is nr_matching_points.
• dir: Sort direction. Possible values are asc to sort entries in ascending order or desc to sort them in descending order. The default value for this attribute is desc.
• include_locations: If set to true, the query response will include an array of locations showing detailed match information about all matching content.
• include_query_stats: If set to true, the query response will include statistics about the query, including how much time each part of the query took.

Response

Query result response will be the same as the original /query response (See Query an image or video)

Example request:

curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     'https://host.videntifier.com/api/v1/query_results/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&include_locations=true'

Query asynchronously

Endpoint

POST /query_async

Required Parameters

Same as /query

Optional Parameters

Same as /query

Response

The async query response will respond with information about the job that was created from the request. The user can then call /jobs with the returned id for further information about the job.

Example request:

curl -X POST \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     -F 'file=@/path/to/file' \
     'https://host.videntifier.com/api/v1/query_async?include_locations=true'

Example response:

{
    "data": {
        "job": {
            "id": "1"
        }
    }
}

Query a video in a "source within" mode

Endpoint

POST /query_sw

Required Parameters

Same as /query

Optional Parameters

• profile: The profile you want to use for the query. Note that if the signature was already computed (e. query by content_id or uploaded as desc72), the profile is ignored.
• include_query_stats: If set to true, the query response will include statistics about the query, including how much time each part of the query took.

Description

When querying a video in a "source within" mode, it queries the database (like default search). It then processes the matches it gets and only returns matches where the query video (the source) is contained within. To detect whether these matches result in a "source within" match, a few things are computed on the database side, including:

1. For each matching video/stream, all query/match locations are grouped together and each group is checked independently for whether its a "source within" match.
2. Each group is given a score based on how many fingerprints it shares with the query video.
3. Each group maintains statistics such as average query percentage, number of unique query locations matching to it, group and query duration, etc.
4. Groups with stats that do not exceed defined minimum values are skipped.
5. For the remaining groups (and this is key), the group score (computed in step 2) is multiplied by the ratio of how much each of the individual stats exceed their minimum value.
6. If the computed score is above a certain minimum value, the group is declared a "source within" match.
7. Based on how much the score is above the minimum, a confidence value is returned. If it just passes the minimum, it gets a confidence value of "1:10". However if the score exceeds the minimum, an increasingly larger confidence value is returned: "1:100","1:1000","1:10000","1:100000" and finally "1:1000000".

This confidence value can be used to indicate weak/strong "source within" matches. For example, if the query video contains logos throughout the bottom that match another different video with a similar logo, then in rare cases this might result in a "source within" match, but then usually the query percentage is lower, causing a low confidence value, which can be filtered out or ignored.

Note

This mode works best when the query video is less than a few minutes long. 30-60 seconds is optimal but it should work rather well for any video shorter than 5 minutes.

Note

This mode is only for querying videos. If you try to query an image, you should get a bad request (code 400) HTTP error

Response

At the root of the JSON query response, the following fields are present:

• query: JSON object with information about performed query. It has the following fields:
  • id: Query response is persisted and can be retrieved at a later time using query result id. Persisted result expires after some time, for details see Retrieve a persisted "source within" query result
  • type: Type of the content queried. Can be only 'video' for source_within queries.
  • download_url: This field is present in the response if the query was performed using URL. It contains the queried URL.
  • content: This object contains information about the queried object (for field description see Get info about an image or video).
  • content_id: This field is present in the response if the query was performed using content id and it contains the content id that was used in the query.
  • file: This field is present in the response if the query was performed using file upload. It contains the filename of the file used.
• visualization_url: URL to the visual user interface where query results can be examined in a browser.
• _metadata: Pagination information.
• query_stats: Query statistics.
• matches: Query result response contains same array of matches as normal /query response (See Query an image or video) with the only difference that source_within response won't contain locations, but will contain parameters confidence and source_within. For their description, see above (Description section).

Example request:

curl -X POST \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     -F 'file=@/path/to/file' \
     'https://host.videntifier.com/api/v1/query_sw'

Example response

{
    "data": {
        "query": {
          "id": "1",
          "type": "image",
          "content_id": "996",
          "content": {
              "content_id": "996",
              "duration": null,
              "metadata": {},
              "url": "https://localhost:9000/data/1f914ad2c9d7bbcbd399ff450ad21e290951d537.png",
              "sha1sum": "1f914ad2c9d7bbcbd399ff450ad21e290951d537",
              "type": "image",
              "filename": "image.jpeg",
              "file_size": "799450",
              "scaled_height": "360",
              "scaled_width": "240",
              "nr_points": "303",
              "created_at": "2018-01-10T05:51:03.658786Z",
              "username": "user1",
              "insert_method": "content"
          }
        },
        "query_stats": {
          "nr_points_queried": "1463",
          "nr_frames_queried": "3",
          "time_fetch_points": "14ms",
          "time_init_matching": "2ms",
          "time_matching": "9ms",
          "time_query": "26ms",
          "time_total_ms": "107ms"
        },
        "_metadata": {
            "page": "1",
            "page_size": "50",
            "nr_pages": "1",
            "nr_results": "1",
            "links": {
                "self": "https://host.videntifier.com/api/v1/query_results_sw/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&page=1&page_size=50",
                "next": null,
                "prev": null,
                "first": "https://host.videntifier.com/api/v1/query_results_sw/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&page=1&page_size=50",
                "last": "https://host.videntifier.com/api/v1/query_results_sw/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&page=1&page_size=50"
            }
        },
        "visualization_url": "https://ui.videntifier.com/api/v1/query_results_sw/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD",
        "matches": [
            {
                "content": {
                    "content_id": "997",
                    "duration": null,
                    "metadata": {},
                    "url": "https://host.videntifier.com/data/3bbbb3248dc4e727545ef1835462ae9954b141ad.jpg",
                    "sha1sum": "3bbbb3248dc4e727545ef1835462ae9954b141ad",
                    "type": "image",
                    "filename": "image.jpg",
                    "file_size": "100495",
                    "scaled_height": "360",
                    "scaled_width": "240",
                    "nr_points": "531",
                    "created_at": "2017-10-11T09:22:44.566794Z",
                    "username": "user1",
                    "insert_method": "content"
                },
                "confidence": "1:10000",
                "source_within": [
                    {
                        "starts_at": "900.38"
                    }
                ]
            }
        ]
    }
}

Retrieve a persisted "source within" query result

Endpoint

GET /query_results_sw/:id

Required Parameters

• access_token: Access token, provided as part of query_result_url from the original query response.

Optional Parameters

• page: Which page to return.
• page_size: How many records to list per page. By default 50 records are returned. The maximum allowed value for this field is 100.
• filter_attr: Attribute used to filter the list of matches. Any of the attributes in match content information can be used as a filter field, as well as a confidence field. This attribute is not set by default.
• filter: Value applied to filter attribute. This attribute is not set by default.
• sort_attr: Attribute used to sort the list of matches. Any of the attributes in match content information can be used as a filter field, as well as confidence field. The default value for this attribute is confidence.
• dir: Sort direction. Possible values are asc to sort entries in ascending order or desc to sort them in descending order. The default value for this attribute is desc.
• include_query_stats: If set to true, the query response will include statistics about the query, including how much time each part of the query took.

Response

The query result response will be same as the /query_sw query response(See Query a video in a "source within" mode)

Example request:

curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     'https://host.videntifier.com/api/v1/query_results_sw/9?access_token=SDnGYgDrMlT4I2F722yYcwirrkBmChSD&include_query_stats=true&include_locations=true'

Query "source within" asynchronously

Endpoint

POST /query_sw_async

Required Parameters

Same as /query_sw

Optional Parameters

Same as /query_sw

Response

The async query_sw response will respond with information about the job that was created from the request. The user can then call /jobs with the returned id for further information about the job.

Example request:

curl -X POST \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     -F 'file=@/path/to/file' \
     'https://host.videntifier.com/api/v1/query_sw_async'

Example response:

{
    "data": {
        "job": {
            "id": "1"
        }
    }
}

Insert an image or video

Endpoint

POST /insert

Required Parameters

The /insert endpoint supports two ways to insert content. You can upload the content or its signature directly by writing it to the form file. You can also provide a download_url that instructs the database to first download the content and then insert it.

• download_url (form-field): A valid URL where the image or video you want to insert can be downloaded from.
• file (form-field): The file path of the image/video/desc72 you want to insert.

Note

If more than one parameter is specified, you will receive an HTTP Bad Request error.

Optional Parameters

• profile: The profile you want to use for the insert. Note that if the signature was already computed (uploaded as desc72), the profile is ignored.
• include_scenes: If set to true, the insert response will include a scenes array listing all scenes attached to the content.
• metadata (form-field): A valid JSON string with any custom metadata you want to save with the inserted content.

Response

The insert response will return the same information as the Get info about an image or video endpoint for the newly inserted content.

Example request:

curl -X POST \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     -F 'file=@/path/to/file' \
     -F 'metadata={"internal_id": "927234"}' \
     'https://host.videntifier.com/api/v1/insert'

Example response:

{
    "data": {
        "content": {
            "content_id": "1001",
            "duration": null,
            "metadata": {
                "internal_id": "927234"
            },
            "url": "https://host.videntifier.com/data/3bbbb3248dc4e727545ef1835462ae9954b141ad.jpg",
            "sha1sum": "3bbbb3248dc4e727545ef1835462ae9954b141ad",
            "type": "image",
            "filename": "image.jpg",
            "file_size": "123456",
            "scaled_height": "360",
            "scaled_width": "240",
            "nr_points": "1234",
            "created_at": "2017-10-11T09:22:32Z",
            "username": "user1",
            "insert_method": "content"
        }
    }
}

Insert asynchronously

Endpoint

POST /insert_async

Required Parameters

Same as /insert

Optional Parameters

Same as /insert

Response

The async insert response will respond with information about the job that was created from the request. The user can then call /jobs with the returned id for further information about the job.

Example request:

curl -X POST \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     -F 'file=@/path/to/file' \
     -F 'metadata={"internal_id": "927234"}' \
     'https://host.videntifier.com/api/v1/insert_async'

Example response:

{
    "data": {
        "job": {
            "id": "1"
        }
    }
}

List jobs

Endpoint

GET /jobs

Required Parameters

None

Optional Parameters

• page: Which page to return.
• page_size: How many records to list per page. By default, 50 records are returned. The maximum allowed value for this field is 100.
• filter_attr: Attribute used to filter the list of jobs. Valid filter field attributes: username, type, status. This attribute is not set by default.
• filter: Value applied to filter attribute. This attribute is not set by default.
• sort_attr: Attribute used to sort the list of jobs. Valid sort field attributes: username, type, status, created_at. The default value for this attribute is created_at.
• dir: Sort direction. Possible values are asc to sort entries in ascending order or desc to sort them in descending order. The default value for this attribute is desc.

Response

The response lists jobs information in jobs array. For details about the fields, see Get job status

curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
    'https://host.videntifier.com/api/v1/jobs?page=1&page_size=2'

{
    "data": {
        "jobs": [
            {
                "id": "3",
                "created_at": "2000-04-24T17:29:21.79949Z",
                "username": "user1",
                "status": "success",
                "method": "content",
                "progress": "0",
                "type": "insert",
                "result_url": "https://host.videntifier.com/api/v1/contents/9971",
                "error": null
            },
            {
                "id": "2",
                "created_at": "2000-04-24T17:29:21.79949Z",
                "username": "user1",
                "status": "success",
                "method": "content_id",
                "progress": "0",
                "type": "query",
                "result_url": "https://host.videntifier.com/api/v1/query_results/2?access_token=bQuzaiUO398OKCEJAw3uFJkx6zfZrbgq",
                "error": null
            }
        ],
        "_metadata": {
            "page": "1",
            "page_size": "2",
            "nr_pages": "1",
            "nr_results": "2",
            "links": {
                "self": "https://host.videntifier.com/api/v1/jobs?page=1&page_size=2",
                "next": null,
                "prev": null,
                "first": "https://host.videntifier.com/api/v1/jobs?page=1&page_size=2",
                "last": "https://host.videntifier.com/api/v1/jobs?page=1&page_size=2"
            }
        }
    }
}

Get job status

Endpoint

GET /jobs/:id

Required Parameters

None

Optional Parameters

None

Response

The response includes the following fields:

• id: The job ID
• username: The username of the user that requested the job.
• created_at: The date when the job was requested.
• status: The status of the job. If it is still processing, it can be any of: download, extract, query, insert. If the job is finished, the status can be: finished, error, cancelled.
• progress: (For videos) The progress of visual point extraction, measured on the scale of 0-100.
• type: The type of the job, can be either query or insert.
• method: The method used to provide the content for the job. If the content to process was uploaded directly to the API, the value will be content. If a remote URL was supplied, the value will be url. If a file with extracted visual points was used instead of the content itself, the value will be desc72. For query jobs only: If the content was queried using its ID within the database, the value of this field will be content_id.
• result_url: If a job finished successfully, this field contains a link to the location of the created resource.
• error: If a job finished with status error, this field will include two fields, code and message. Otherwise it will be null.

The response will tell you whether the job is finished or not. If not finished, it will return status 200. For videos, the field progress will indicate visual point extraction progress. If the job is finished, the request will return a status 303 with a link to the newly created resource in field Location in the header.

Example request (-i to include header response):

curl -i -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
    'https://host.videntifier.com/api/v1/jobs/1'

Example response from finished job:

HTTP/1.1 303 See Other
Access-Control-Allow-Headers: Accept, Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization
Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE
Access-Control-Allow-Origin: *
Content-Type: application/json
Location: https://host.videntifier.com/api/v1/query_results_sw/2?access_token=xq87GN7JoX2AeXeyJWNtyR9Euz2CQQxq
Date: Mon, 29 Jan 2018 15:40:27 GMT
Content-Length: 0

{
    "data": {
        "job": {
            "id": "1",
            "created_at": "2000-04-24T17:29:21.79949Z",
            "username": "user1",
            "status": "success",
            "method": "content_id",
            "progress": "0",
            "type": "query",
            "result_url": "https://host.videntifier.com/api/v1/query_results_sw/2?access_token=xq87GN7JoX2AeXeyJWNtyR9Euz2CQQxq",
            "error": null
        }
    }
}

Example response from processing job:

HTTP/1.1 200 OK
Access-Control-Allow-Headers: Accept, Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization
Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Mon, 29 Jan 2018 15:42:12 GMT
Content-Length: 33

{
    "data": {
        "job": {
            "id": "1",
            "created_at": "2000-04-24T17:29:21.79949Z",
            "username": "user1",
            "status": "extract",
            "method": "content_id",
            "progress": "38",
            "type": "query",
            "result_url": null,
            "error": null
        }
    }
}

Example response from failed job:

HTTP/1.1 200 OK
Access-Control-Allow-Headers: Accept, Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization
Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Mon, 29 Jan 2018 15:42:12 GMT
Content-Length: 33

{
    "data": {
        "job": {
            "id": "1",
            "created_at": "2000-04-24T17:29:21.79949Z",
            "username": "user1",
            "status": "error",
            "method": "content_id",
            "progress": "0",
            "type": "query",
            "result_url": null,
            "error": {
                "code": "500",
                "message": "Internal Server Error"
            }
        }
    }
}

Delete job

Endpoint

DELETE /jobs/:id

Required Parameters

None

Optional Parameters

None

Response

If the job is being actively processed at the time of the delete request, the request will return a 409 conflict status code.

Example request:

curl -X DELETE \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     'https://host.videntifier.com/api/v1/jobs/2'

Example response:

{
    "data:": {
        "message": "Resource has been deleted"
    }
}

List inserted images and videos

Endpoint

GET /contents

Required Parameters

None

Optional Parameters

• include_matches: If set to true, each content will include an array of matching contents.
• include_scenes: If set to true, each content will include an array of scenes attached to the content.
• include_points: If set to true, each content will include an array of visual point coordinates. Currently this feature is only supported for images.
• page: Which page to return.
• page_size: How many records to list per page. By default 50 records are returned. The maximum allowed value for this field is 100.
• filter_attr: Attribute used to filter the list of contents. Any of the attributes in content information can be used as a filter field. This attribute is not set by default.
• filter: Value applied to filter attribute. This attribute is not set by default.
• sort_attr: Attribute used to sort the list of contents. Any of the attributes in content information can be used as a sort field. The default value for this attribute is created_at.
• dir: Sort direction. Possible values are asc to sort entries in ascending order or desc to sort them in descending order. The default value for this attribute is desc.

Response

The response lists inserted contents information in contents array. For details about the fields, see Get info about an image or video

Example request:

curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     'https://host.videntifier.com/api/v1/contents?include_scenes=true&include_matches=true'

Example response:

{
    "data": {
        "_metadata": {
            "page": "1",
            "page_size": "50",
            "nr_pages": "1",
            "nr_results": "1",
            "links": {
                "self": "https://host.videntifier.com/api/v1/contents?page=1&page_size=50",
                "next": null,
                "prev": null,
                "first": "https://host.videntifier.com/api/v1/contents?page=1&page_size=50",
                "last": "https://host.videntifier.com/api/v1/contents?page=1&page_size=50"
            }
        },
        "contents": [
            {
                "content_id": "1000",
                "duration": null,
                "metadata": {},
                "url": "https://host.videntifier.com/data/913238e963e854d4909ba920eed4e6cceb5c5360.jpg",
                "sha1sum": "913238e963e854d4909ba920eed4e6cceb5c5360",
                "type": "image",
                "filename": "3.jpg",
                "file_size": "100495",
                "scaled_height": "360",
                "scaled_width": "240",
                "nr_points": "543",
                "created_at": "2017-10-11T09:22:44.566794Z",
                "username": "user1",
                "insert_method": "content",
                "matches": [
                    {
                      "content_id": "1002",
                      "duration": null,
                      "metadata": {},
                      "url": "https://host.videntifier.com/data/ba920eed4e6cceb5c5360913238e963e854d4909.jpg",
                      "sha1sum": "ba920eed4e6cceb5c5360913238e963e854d4909",
                      "type": "image",
                      "filename": "9.jpg",
                      "file_size": "4950",
                      "scaled_height": "360",
                      "scaled_width": "280",
                      "nr_points": "845",
                      "created_at": "2017-10-11T01:20:40.794566Z",
                      "username": "user1",
                      "insert_method": "content"
                    }
                ],
                "scenes": [
                    {
                        "locations": [],
                        "scene_id": "1001"
                    }
                ]
            }
        ]
    }
}

Get info about an image or video

Endpoint

GET /contents/:id

Required Parameters

None

Optional Parameters

• include_matches: If set to true, the content will include an array of matching contents.
• include_scenes: If set to true, the content will include an array of scenes attached to the content.
• include_points: If set to true, the content will include an array of visual point coordinates. Currently this feature is only supported for images.

Response

The response includes following fields:

• content_id: The contentID of the inserted content.
• created_at: The date when the content was inserted.
• duration: The duration of the video in seconds or null if the content is an image.
• file_size: The file size of the content.
• scaled_height: The height used when calculating the visual points for the media.
• scaled_width: The width used when calculating the visual points for the media.
• filename: The filename of the content.
• insert_method: How the content was inserted, possible values are content, url or desc72.
• nr_points: The number of visual points extracted from the content that were inserted into the database.
• metadata: Custom metadata attached to the content.
• sha1sum: The sha1sum of the content.
• type: The type of content (image or video).
• url: A direct URL to the content. If the insert_method is desc72 then URL is null as the content is not stored in the database.
• username: The username of the user who inserted the content.
• scenes: If the include_scenes query param is set to true, this will contain JSON array with following fields:
  • locations: A list of locations which the scene describes.
  • scene_id: The sceneID of the inserted scene describing the image or video scene.

Example request:

curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     'https://host.videntifier.com/api/v1/contents/1000?include_scenes=true&include_points=true&include_matches=true'

Example response:

{
    "data": {
        "content": {
            "content_id": "1000",
            "duration": null,
            "metadata": {},
            "url": "https://host.videntifier.com/data/913238e963e854d4909ba920eed4e6cceb5c5360.jpg",
            "sha1sum": "913238e963e854d4909ba920eed4e6cceb5c5360",
            "type": "image",
            "filename": "3.jpg",
            "file_size": "100495",
            "scaled_height": "360",
            "scaled_width": "240",
            "nr_points": "543",
            "created_at": "2017-10-11T09:22:44.566794Z",
            "username": "user1",
            "insert_method": "content",
            "matches": [
                {
                    "content_id": "1002",
                    "duration": null,
                    "metadata": {},
                    "url": "https://host.videntifier.com/data/ba920eed4e6cceb5c5360913238e963e854d4909.jpg",
                    "sha1sum": "ba920eed4e6cceb5c5360913238e963e854d4909",
                    "type": "image",
                    "filename": "9.jpg",
                    "file_size": "4950",
                    "scaled_height": "360",
                    "scaled_width": "280",
                    "nr_points": "845",
                    "created_at": "2017-10-11T01:20:40.794566Z",
                    "username": "user1",
                    "insert_method": "content"
                }
            ],
            "scenes": [
                {
                    "locations": [],
                    "scene_id": "1001"
                }
            ],
            "points": [
                {
                    "x": "15",
                    "y": "123"
                }
            ]
        }
    }
}

Delete an image or video

Endpoint

DELETE /contents/:id

Required Parameters

None

Optional Parameters

None

Response

Example request:

curl -X DELETE \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     'https://host.videntifier.com/api/v1/contents/999'

Example response:

{
    "data:": {
        "message": "Resource has been deleted"
    }
}

Update metadata

Endpoint

PUT /contents/:id/metadata

Required Parameters

• metadata (form-field): The new metadata you want to save.

Optional Parameters

None

Response

This endpoint updates the metadata attached to the specified content. The new metadata will replace the existing metadata (if any).

Example request:

curl -X PUT \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     -F 'metadata={"internal_id": "927234", "internal_name": "ab2281_11"}' \
     'https://host.videntifier.com/api/v1/contents/1000/metadata'

Example response:

{
    "data:": {
        "message": "Metadata was updated successfully"
    }
}

List users

Endpoint

GET /users

Required Parameters

None

Optional Parameters

• page: Which page to return.
• page_size: How many records to list per page. By default, 50 records are returned. The maximum allowed value for this field is 100.
• filter_attr: Attribute used to filter user list. Any of the attributes in user information can be used as a filter field. This attribute is not set by default.
• filter: Value applied to filter attribute. This attribute is not set by default.
• sort_attr: Attribute used to sort user list. Any of the attributes in user information can be used as a sort field. The default value is username.
• dir: Sort direction. Possible values are asc to sort entries in ascending order or desc to sort them in descending order. The default value is asc.

Response

The response lists all registered users. Each user information has the following fields:

• id: The ID of the user.
• username: The username of the user.
• email: The email of the user.
• api_token: API token of the user. API token is not displayed in cases when the user doesn't have necessary rights to view it.
• can_insert: Signifies whether the user has right to insert content. Possible values are true or false.
• role: User's role. Possible values are admin or basic. Role basic allows basic API usage, while role admin allows to modify/delete all content and users.
• visibility: User's visibility setting. Possible values are private, public or global. Contents inserted by the user with private visibility setting can only be viewed/searched by this user. Contents inserted by the user with public visibility setting can be viewed/searched by any other user within the same organization. Contents inserted by the user with global visibility setting can also be viewed/searched by other organizations.

Example request:

curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     'https://host.videntifier.com/api/v1/users?sort_attr=id&dir=desc&filter_attr=username&filter=vid'

Example response:

{
    "data": {
        "users": [
            {
                "id": "1",
                "username": "user1",
                "email": "videntifier@videntifier.com",
                "api_token": "tw3v2Ep1K94ohFZPHQPX",
                "can_insert": true,
                "role": "admin",
                "visibility": "global"
            }
        ],
        "_metadata": {
            "page": "1",
            "page_size": "50",
            "nr_pages": "1",
            "nr_results": "1",
            "links": {
                "self": "https://host.videntifier.com/api/v1/users?dir=desc&filter=vid&filter_attr=username&page=1&page_size=50&sort_attr=id",
                "next": null,
                "prev": null,
                "first": "https://host.videntifier.com/api/v1/users?dir=desc&filter=vid&filter_attr=username&page=1&page_size=50&sort_attr=id",
                "last": "https://host.videntifier.com/api/v1/users?dir=desc&filter=vid&filter_attr=username&page=1&page_size=50&sort_attr=id"
            }
        }
    }
}

Create user

Endpoint

POST /users

Required Parameters

• email (form-field): The email of the user. It has to be unique.
• username (form-field): The username of the user. It has to be unique.

Optional Parameters

• can_insert (form-field): Signifies whether the user has the right to insert content. Possible values are true or false. The default value is set to true.
• role (form-field): User's role. Possible values are admin or basic. Role basic allows basic API usage, while role admin allows to modify/delete all content and users. The default value for this attribute is set to basic.
• visibility (form-field): User's visibility setting. Possible values are private or public. Contents inserted by the user with private visibility setting can only be viewed/searched by this user. Contents inserted by the user with public visibility setting can be viewed/searched by any other user. The default value for this attribute is set to public.

Response

The user creation response will return the same information as the Get info about user endpoint for the newly created user. If a user with such username or email already exists, API will return an error message describing conflict type.

Note

You can only create users if you have admin role.

Note

API automatically generates an API token when creating a user. Remember to provide it to the user so that he can use the API.

Example request:

curl -X POST \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
         -F 'email=user1@videntifier.com' \
         -F 'username=user1' \
         -F 'can_insert=false' \
         -F 'role=admin' \
         -F 'visibility=private' \
         'https://host.videntifier.com/api/v1/users' 

Example response:

{
    "data": {
        "id": "23",
        "username": "user1",
        "email": "user1@videntifier.com",
        "api_token": "iY4bkbEYYDQX31NmWvji",
        "can_insert": false,
        "role": "admin",
        "visibility": "private"
    }
}

Update user information

Endpoint

PATCH /users/:id

Required Parameters

None

Note

Even though no parameters are required, one of the optional parameters should always be supplied. On no parameters, you will receive bad request (code 400) HTTP error.

Optional Parameters

• can_insert (form-field): Signifies whether the user has right to insert content. Possible values are true or false.
• email (form-field): The email of the user. It has to be unique.
• role (form-field): User's role. Possible values are admin or basic. Role basic allows basic API usage, while role admin allows to modify/delete all content and users.
• username (form-field): The username of the user. It has to be unique.
• visibility (form-field): User's visibility setting. Possible values are private or public. Contents inserted by the user with private visibility setting can only be viewed/searched by this user. Contents inserted by the user with public visibility setting can be viewed/searched by any other user.

Response

Note

You can only update other users' information if you have admin role. If you have basic role, you can update your own user information, but you cannot change your role.

This endpoint updates attributes of the user specified in the request. Attributes that were not specified will not be updated.

Example request:

curl -X PATCH \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     -F 'email=james@videntifier.com' \
     -F 'role=basic' \
     'https://host.videntifier.com/api/v1/users/23'

Example response:

{
    "data:": {
        "message": "User has been updated successfully"
    }
}

Delete user

Endpoint

DELETE /users/:id

Required Parameters

None

Optional Parameters

None

Response

Note

You can only delete users if you have admin role. You can also delete your own account. Contents inserted by deleted users will not be deleted and will continue to appear in search results unless removed separately (See Delete an image or video).

This endpoint deletes the user using provided user id.

Example request:

curl -X DELETE \
     -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     'https://host.videntifier.com/api/v1/users/23'

Example response:

{
    "data:": {
        "message": "User has been deleted successfully"
    }
}

Get info about user

Endpoint

GET /users/:id

Required Parameters

None

Optional Parameters

None

Response

The response lists information about the user. It includes the same fields as described in List users

Example request:

curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     'https://host.videntifier.com/api/v1/users/23'

Example response:

{
    "data": {
        "id": "23",
        "username": "user1",
        "email": "user1@videntifier.com",
        "api_token": "iY4bkbEYYDQX31NmWvji",
        "can_insert": false,
        "role": "admin",
        "visibility": "private"
    }
}

Get info about database

Endpoint

GET /dbinfo

Required Parameters

None

Optional Parameters

None

Response

The response lists information about the database. It has the following fields:

• type: The type of database. Possible values are nvtree, nvtree-ssd or nvdb.
• nr_points: Number of visual points stored in the database.
• nr_scenes: Number of scenes stored in the database.
• nr_searches_last_day: Number of searches performed on the database during the last day.
• nr_searches_last_hour: Number of searches performed on the database during the last hour.
• nr_searches_last_minute: Number of searches performed on the database during the last minute.
• nr_threads: Number of threads the database is using.
• location: Database location on the disk.
• app_version: Version of the application through which API interacts with the database.
• db_version: Version of the database.

Example request:

curl -H 'Authorization: tw3v2Ep1K94ohFZPHQPX' \
     'https://host.videntifier.com/api/v1/dbinfo'

Example response:

{
    "data": {
        "type": "nvtree",
        "nr_points": "9507666",
        "nr_scenes": "171",
        "nr_searches_last_day": "130",
        "nr_searches_last_hour": "25",
        "nr_searches_last_minute": "2",
        "nr_threads": "16",
        "location": "/home/videntifier/.videntifier/testdatabase",
        "app_version": "1.0",
        "db_version": "5.1.0-3a9aa4e"
    }
}

Related matches

Related matches are contents that don't match the queried content directly, but are related to it indirectly through the other matched contents. Related matches are found by performing a breadth-first search on the direct matches. Related matches contain the same content object as the direct matches (see Query an image or video). However, in addition to the content object, related matches will have fields with the following extra information:

• related_depth: This field describes the matching distance from the original match. In the provided diagram, related matches of the direct matches have related_depth equal to 1. The contents matching the first depth level of related matches will have a depth equal to 2, and so on.
• related_content_id: This field contains a content id of the "parent match", which is a match that resulted in the current related match. In the provided diagram, related matches with a depth of 1 have a content_id of the direct match in the related_content_id field.

Searching for related matches immediately returns results when any of the following conditions are met:

• all of the related matches are found
• a matching depth reaches level 6
• total number of the found related matches equals (or exceeds) 100 items

To eliminate low-matching contents, each related match needs to match at least 10% against their parent match (and vice versa, parent match needs to match at least 10%). For example, the related match will not qualify if a very small part of the query image (<10%) matches a large part of the match image.

Note

Related matches are currently only available for the images. Video matches will not result in related matches.