Direct API requests to tntapi

You can use HTTP API to extract data directly from the tntapi.

In this section:

General Information

API requests to tntapi are to be sent to http://<tnt_api_host_ip:port>.

Tip

The port for API requests can be found in the environment CFG_LISTEN_PORT:

docker exec -ti tnt-1-1 env
docker exec -ti tnt-1-1 env | grep CFG_LISTEN
CFG_LISTEN_HOST=0.0.0.0
CFG_LISTEN_PORT=8001

API requests to tntapi may contain the following parameters in path segments:

  • API version only v2 at the moment.

  • :name: gallery name.

Node status

GET /v2/status

This method returns read_only node status and repeat header "X-read-only" value. If the value is "true" it means that the tntapi node has follower status and only read operations are available. Otherwise, if the value is "false", it means that the tntapi node has leader status, read and write operations with the node are available.

Returns:

  • HTTP 200 and list with null values on success.

  • HTTP with a status other than 200 and an error description in the body on failure.

Example

Request

curl -D - -X GET -s 'http://localhost:8001/v2/status'

Response

HTTP/1.1 200 Ok
X-request-id: TN:cU4qiMGc
Content-type: application/json
X-read-only: false
Content-length: 19
Connection: keep-alive
Server: Tarantool http (tarantool v2.10.4-2-gd536a7aa5)

{"read_only":false}

Add Face

POST /v2/faces/add/:name[?return_face=false]

Parameters in path segments:

  • :name: gallery name.

  • return_face: non-required parameter (default value false).

Parameters in body:

JSON-encoded array of faces with the following fields:

  • "id": face id in the gallery, uint64_t.

  • "facen": raw feature vector, base64.

  • "facen_model": facen model name, string.

  • "meta": face metadata, dictionary.

The field "facen_model" is not required. When adding the first face to the gallery, the value will be saved in the gallery. Otherwise, if there is already a saved value in the gallery, it will be checked. If the values in the request and in the gallery are different, the error 400 Gallery[:name]: facen model mismatch: required :exp_val, got :val will be returned.

Returns:

  • HTTP 200 and a list with null values on success. If "return_face=true" is specified in the request, "id" and "meta" will be returned for successfully added faces.

  • HTTP 404 if a gallery with the given name doesn’t exist.

  • HTTP with a status other than 200 and error description in the body on failure.

Example

Request

curl -D - -s 'http://localhost:8001/v2/faces/add/testgal' --data '
[
  {
    "id": 9223372036854776000,
    "facen": "qgI3vZRv/z0BQTk9rcirOyZrE72yi047zl9gPSER2zxKyds9CjfCPQvR071z02S9mU0/vVOVEj3SiZw8Q4Q9vViRFjo4Hqi8lc4wvDxcHT1kfpC82uVCPYEHr73RRMS7TVQpPCPUNjxXqZs99NqOvXbPEzxYsOQ9SL/CvG3w4L0h4pG96nvBvTo85TwLByY8H2XMPQ3anb03FV68q/UKPLCdlr3K6Kk9H4NSvAQnHD3nAmc7A1RAPZ8BgLzMZu47KwRovbC+PzzISL68vaYPvUfP1D1//EM9xYZpvEaeGb3Gnti9/n+VPZnONz2xQVW8fGNCPduV2DwGsaG74eCWvNdLy7yjFUe9skvtPJStxbvXk0O9C6nRPJj14zzR+iq9L8WqPWK8vr1OFAy91M8APZoPTD3GlKI9vpjSuqsvMj1DY829z7zIu7oXkb2rUbM96KrLPB0FpTy6Ol89WquuvP4+qz1Vhmm9BupkvcWzH7zHlTY9OkwRPaM3rzwL0UE9dIT0vJUAHz3LaQc8JJsUPcAVwLyZwRe9iIufPWXLvbqThLY950RfvaETlL0/1Uy8ML+Euxl+1LzxbpG9FIDxvEPqur3WdHW9IDRRPfro6L0mSp88z6aivSmzrr3a4Qa+2Q3luyOatDwhaCI9AFecvPjA3jwb5B29uSjJPFuPsr1aR2a9WJ+jPAD65b27Iw29uEZrvYebHL2xk6u9rTIkvtZgaL0/9x49GeDyu+jjRr0RqPu8GqYgvf9piz183C490197Pe76gTvMUoY8oQBUPRjL1z2E95C83jcSPJIFML15SxG8ukGMPP1/8bxoXIw9vYkevSMcKb2vmw69PM4+vftBxz068tA97uNLvSwazjxpMJu9N1akPHBDmz12c8Y8W08hPA3DpD1cOsC8lOc6PZCxh73EXq09BMl6PUhfAj0sEK28fyh2vIyTOj07gzY9nqRfvTeQ/L3y2Ta77Bu+PbpY57ymrfU8IayRvZaLEz00w/a9n42WOk23jbxZ4t49q1soPdB0ED39OXu8DhMYvbPRYz011C88WBiBvae8zrwL6Yk8GdTrPONJOz2GIxO8R+lmO2rwR73WOGm9JC0tPXNg/r2XDVC7XdhtPb9vgrxdUZQ9GJ06PTCGJTsDAS09/dgqPYT0ej20BjW+NPE7PLP3C7mTy4s85D5iPHrbUT3+3xA9Fcg0PCSdLD3AFbg82byAPC4doDymsHS8cvk3vJHogruI+ig9+qiWvSj+w7x7TFE8f6kXvEeAqz3Lcqs8K5envJXVxDwqbKU8KaFRvFxQ1bx+WNS8WuSAPSfHyTzFkWy93J0gPecFMTtNRlG9Ae3PvWd6JD13SC48wG7JvCxJhDwsxyW9BeAHPfe9oLueZO09UJDLvK+Uq7rsggk+ja8EO1ejozwgkjI+2kK2PLedhDw4Y/O8S19rvRPXZz2aVcI9+OUcvCfdjT0ocIm9c3vju97AE72sI4w9rHuYPexB+TywgcU7fkQyumxQgr0Ik9g66oFGPSeljjxayPG8WBj+Pce4tL2EdgS90s/UPJ5Fsr3P46y9fOpGvfC9ojtO5Ao9nqRUvbUNYz00+KE8WgZyvKsWlD0YTma9hu2tPTX2ZD3kZ967tCJuvEADurxYUnO9Ezs1vdIGUT2N9IO9hligPU7BEr3l4aE729c5vNV/hD0/NpO9MdHavW1WuT0=",
    "meta": {
      "cam_id": "223900",
      "person_id": "123"
    }
  }
]'

Response

HTTP/1.1 200 Ok
X-request-id: TN:T39tIFME
Content-type: application/json
X-read-only: false
Content-length: 60
Connection: keep-alive
Server: Tarantool http (tarantool v2.10.4-2-gd536a7aa5)

[null,{"error":{"code":400,"message":"face 'id' required"}}]

Remove Face

POST /v2/faces/delete/:name

Parameters in path segments:

  • :name: gallery name.

Parameters in body:

JSON-encoded array of face ids to be removed.

Returns:

  • HTTP 200 and a list of error values on success:

    • null if face was successfully removed.

    • {"error": {"code": 404, ...}} if a face did not exist.

  • HTTP 404 if a gallery with the given name doesn’t exist.

  • HTTP with a status other than 200 and error description in the body on failure.

Example

Request

curl -D -  -s 'http://localhost:8001/v2/faces/delete/testgal' --data '[1, 4, 922, 3]'

Response

HTTP/1.1 200 Ok
X-request-id: TN:sgi6xdVO
Content-type: application/json
X-read-only: false
Content-length: 6
Connection: keep-alive
Server: Tarantool http (tarantool v2.10.4-2-gd536a7aa5)

[null, null, null, null]

Edit Face Metadata and/or Feature Vector

POST /v2/faces/update/:name

Parameters in path segments:

  • :name: gallery name.

Parameters in body:

JSON-encoded array with faces with the following fields:

  • "id": face id, uint64_t.

  • "facen": (optional) new feature vector, base64. If omitted or passed as null, the relevant field in the database won’t be updated.

  • "meta": dictionary with metadata to be updated. If some metastring is omitted or passed as null, the relevant field in the database won’t be updated.

Returns:

  • HTTP 200 and a list of update results on success:

    • a dictionary with all face parameters, including not updated, on success.

    • {error: {code: ..., ...}} if there is an error.

  • HTTP 404 and an error description if a face with the given id doesn’t exist.

  • HTTP with a status other than 200 and an error description in the body on failure.

Example

Request

curl -D - -s 'http://localhost:8001/v2/faces/update/testgal' --data '
[
   {
         "id": 9223372036854776002,
         "facen": "sy2BPb3xrz1ffbY9QJ0sPTlpAD2D+5A91tgePCIdGDwjSfQ8SupkPNMv2jwS5o48BvHNPETWWD3qSFo6zDp6PaiDpT3FHjA9lK+yPdxFKj2pJEc86uugPe2cpz1u8oM9OZ2NPWNKBT20D6U8+qwhPP/SKTvPP8s8E4v2PB6lnz2A7SQ9UK0gPRTxLz3Ukrg991C7PfrsZz0thTs9BwQQPVwvuj3/iAM8/TaLPHg4pjzwvy49jwzTPHk/pz2QpTc9lAelPLV3Az3WJgI9sT2gPXdgwD0oKoc9mzaxPTe52TweKZo9+GW6PThnYz3i4HM9SgQrPVq4qD0CUQI8JrmfPcXoMD3vX4k85SVWPSDfhT29YTs8/BXCPHMSrj1JNDw9nze5PRbYtT2xN5w9Ms0uPWWd5jwLixg9LLCBPb2sxzyLa4E8xpumPeM8gTzcuos8KdG+PctOWT2LmMo8ot58PVwdrD2LmH48pbMrPTGrPj3fqKM9haB4PHlVUzzGIr88/VGhPUzHBz2GTtg81YT8PKAtjzsmPbM9jkebPRSWBD01ADQ9Pl1MPYRbkT0A2ME97T8fPULMoT1j7oc9FE0sOq71rj2VGz49gewcPeU8mj2jlCA8oOSlOO0SvD2GBFA9ItsRPIokXTxYSyg9l6+wPaDemz1L3rw9QhcsPNo9Sj0Zw7g9Z3IdPTuLLD1s73o9uiTBPchmgTxt3yU9ByLpPOqstTxW/F89WeurPW3FUjxOtQE9uz6NPdhKCT2vlII9xwETPQbQED0Uubg93vyrPXmgrTy/HmM92vPCPcEdzjtPgTo86vY3PQpupT0gM389L7EUPQtfaTtljrA9fqGDPem41TvlMKc8PjV7PZs8hj2KJLg9RiX2PPopvT12GoM9vmm5PTrF3DwJyI08p2CxPD/ngj0fhzI9WPVDPZSnPT0PeuI7M/C3PUemcj0HKOY8cIvDPYkwQT0Bx148YfvcOzgBXj1V19Y84oG6PfzCvT2baFs9MLy6PVfA+zzsTY48S6uoPUOoHz0ERhE8f4JgPa/Skjwh94g9RiQ6PWJLXz1CCKo9SlTKPAQwDz2UKPw8BAH+PPjPFj1Sm6w9uRVHPbwX+TxMaF491OuxPd0CnT0KYo09DhsxPU00wTzunUA9KDOkPLA6yzzSWbI96T6aPfwdpz0LvKY8Rz4+PbtCCz0LDr89IVsgOzQ3BT0ZxdM7E9yVPPWU3Dw0jJw9rid9PUMhQD1hfxA6G0wYPeqEuD1twYg9fkupPQepqT0jt3U9oNDIPK420DxB8vI89sG2PTPngz3lbgM9JQn5O0zOMD3Vd6A7oRtIPeM9uz0dUoE7xyCqO1brOj0lPp479mNEPYcYoz1S2q48GiCEOnuNTTz/qMs8M16JPLp7xD3EHh89BHyPPdSsmD2qcnA9S2GlPEBMoT2Ih7s9gyYOPfG2sDzLlP88lNx1PTA3mz0Befg8gryUPbBpyDsesqE9lSc8PcCNiT0d1bw9UDmoPAwLOT3OPas9ZJO2PRcNrz2+kIg9E7GCPXTmtD0Ku7g9kaN/PfkQGz00sl09kZewOnUuBzsgm/I8oYojOi/d7jxmrzk8G2ITPfxqiT3OqyY9WwRqPZ4OWT0BtI0983dOPeGxgD0CECA928C1PLbbujx8f2U8WpwSPfjElD3Hq6s94BRgPcsTuTx66b490c4JPW1dxD0=",
         "meta": {
           "timestamp": 350
         }
   }
]'

Response

HTTP/1.1 200 Ok
X-request-id: TN:hsMZrt0g
Content-type: application/json
X-read-only: false
Content-length: 1847
Connection: keep-alive
Server: Tarantool http (tarantool v2.10.4-2-gd536a7aa5)

[{"meta":{"timestamp":350,"photo_hash":"","tags":[],"person_id":123,"cam_id":"223900"},"id":9223372036854776002,"facen":"sy2BPb3xrz1ffbY9QJ0sPTlpAD2D+5A91tgePCIdGDwjSfQ8SupkPNMv2jwS5o48BvHNPETWWD3qSFo6zDp6PaiDpT3FHjA9lK+yPdxFKj2pJEc86uugPe2cpz1u8oM9OZ2NPWNKBT20D6U8+qwhPP\/SKTvPP8s8E4v2PB6lnz2A7SQ9UK0gPRTxLz3Ukrg991C7PfrsZz0thTs9BwQQPVwvuj3\/iAM8\/TaLPHg4pjzwvy49jwzTPHk\/pz2QpTc9lAelPLV3Az3WJgI9sT2gPXdgwD0oKoc9mzaxPTe52TweKZo9+GW6PThnYz3i4HM9SgQrPVq4qD0CUQI8JrmfPcXoMD3vX4k85SVWPSDfhT29YTs8\/BXCPHMSrj1JNDw9nze5PRbYtT2xN5w9Ms0uPWWd5jwLixg9LLCBPb2sxzyLa4E8xpumPeM8gTzcuos8KdG+PctOWT2LmMo8ot58PVwdrD2LmH48pbMrPTGrPj3fqKM9haB4PHlVUzzGIr88\/VGhPUzHBz2GTtg81YT8PKAtjzsmPbM9jkebPRSWBD01ADQ9Pl1MPYRbkT0A2ME97T8fPULMoT1j7oc9FE0sOq71rj2VGz49gewcPeU8mj2jlCA8oOSlOO0SvD2GBFA9ItsRPIokXTxYSyg9l6+wPaDemz1L3rw9QhcsPNo9Sj0Zw7g9Z3IdPTuLLD1s73o9uiTBPchmgTxt3yU9ByLpPOqstTxW\/F89WeurPW3FUjxOtQE9uz6NPdhKCT2vlII9xwETPQbQED0Uubg93vyrPXmgrTy\/HmM92vPCPcEdzjtPgTo86vY3PQpupT0gM389L7EUPQtfaTtljrA9fqGDPem41TvlMKc8PjV7PZs8hj2KJLg9RiX2PPopvT12GoM9vmm5PTrF3DwJyI08p2CxPD\/ngj0fhzI9WPVDPZSnPT0PeuI7M\/C3PUemcj0HKOY8cIvDPYkwQT0Bx148YfvcOzgBXj1V19Y84oG6PfzCvT2baFs9MLy6PVfA+zzsTY48S6uoPUOoHz0ERhE8f4JgPa\/Skjwh94g9RiQ6PWJLXz1CCKo9SlTKPAQwDz2UKPw8BAH+PPjPFj1Sm6w9uRVHPbwX+TxMaF491OuxPd0CnT0KYo09DhsxPU00wTzunUA9KDOkPLA6yzzSWbI96T6aPfwdpz0LvKY8Rz4+PbtCCz0LDr89IVsgOzQ3BT0ZxdM7E9yVPPWU3Dw0jJw9rid9PUMhQD1hfxA6G0wYPeqEuD1twYg9fkupPQepqT0jt3U9oNDIPK420DxB8vI89sG2PTPngz3lbgM9JQn5O0zOMD3Vd6A7oRtIPeM9uz0dUoE7xyCqO1brOj0lPp479mNEPYcYoz1S2q48GiCEOnuNTTz\/qMs8M16JPLp7xD3EHh89BHyPPdSsmD2qcnA9S2GlPEBMoT2Ih7s9gyYOPfG2sDzLlP88lNx1PTA3mz0Befg8gryUPbBpyDsesqE9lSc8PcCNiT0d1bw9UDmoPAwLOT3OPas9ZJO2PRcNrz2+kIg9E7GCPXTmtD0Ku7g9kaN\/PfkQGz00sl09kZewOnUuBzsgm\/I8oYojOi\/d7jxmrzk8G2ITPfxqiT3OqyY9WwRqPZ4OWT0BtI0983dOPeGxgD0CECA928C1PLbbujx8f2U8WpwSPfjElD3Hq6s94BRgPcsTuTx66b490c4JPW1dxD0="}]

List Galleries

POST /v2/galleries/list

Returns:

JSON-encoded array with galleries with the following fields:

  • space: space name,

  • name: gallery name,

  • faces: number of faces in a gallery.

Example

Request

curl -D - -s -X POST http://localhost:8001/v2/galleries/list

Response

HTTP/1.1 200 Ok
X-request-id: TN:6iRqT5FR
Content-type: application/json
X-read-only: false
Content-length: 60
Connection: keep-alive
Server: Tarantool http (tarantool v2.10.4-2-gd536a7aa5)

{"results":[{"space":"default","name":"testgal","faces":0}]}