Custom Search allows you to search your own image data for visual matches to a query image. It allows you to build and maintain an individualized database of images and submit images for model-based comparisons to this reference set. You can read more about our Custom Search product in our guide pages.

Authentication

Each Custom Search project has a unique API key that will need to be included in the API request. The API key will be sent via email after signing up for the project.

👍

Include the API Key in the header of your POST request ('authorization: token <YOUR_API_KEY>'). The API keys to authenticate tasks is the same for all three endpoints (add, query, remove).

Add to the Custom Index

https://api.thehive.ai/api/v2/custom_index/add/sync
https://api.thehive.ai/api/v2/custom_index/add/async

Form Data

Field (*required)

Type

Description

url

String

Image url (publicly hosted media)

media

File

Image file (jpg, png, webp)

metadata

String

User-provided metadata that will be returned in the Query Endpoint Response.

callback_url* (for async API requests)

String

Callback url where we will post Success/Failure response.

Add API Sample Response

//some fields truncated for clarity
{
    "id": "bd70fb00-c108-11ec-98ca-29cfab89986e",
    "code": 200,
    "project_id": 275729,
    "user_id": 331,
    "created_on": "2022-04-21T00:19:45.708Z",
    "status": [
        {
            "status": {
                "code": "0",
                "message": "SUCCESS"
            },
           //truncated
                },
                "output": {
                    "status": "Success",
                    "shaHash": "3e9065a9eecb53fdb79aabce42e72cc52c0743baa6afc52e4132af5a204b36cb",
                    "message": "Image successfully added to the index"
                }
            }
        }
    ],
    "from_cache": false,
    "metadata": "\"sample metadata string\" "
}

Query your Custom Index

https://api.thehive.ai/api/v2/custom_index/query/sync
https://api.thehive.ai/api/v2/custom_index/query/async

Form Data

Field (*required)

Type

Description

url

String

Image url (publicly hosted media)

media

File

Image file (jpg, png, webp)

callback_url* (for async API requests)

String

Callback url where we will post Success/Failure response and query results. Only required for async requests

Query API Sample Response

//some fields truncated for clarity
{
  "task_id": "dd52c0d0-9ec7-11ea-98a3-4b92424b8366",
  "project_id": 18416,
  "response":
    {
      //truncated
      "output": {
            "matches": [
                {
                  "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/violence/violence_4.jpg",
                  "id": "b2ff8040-a4a9-11ec-8936-9f134fd475df",
                  "similarity_score": 1.00,
                  "metadata": "this is the metadata submitted by you for this image"
                },
                {
                  "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg",
                  "id": "h4j34jar-a4a9-11ec-8936-9f134fd475df",
                  "similarity_score": 0.97,
                  "metadata": "this is the metadata submitted by you for this image"
                }
              ]                
      }
    }
}

Remove Images from the Custom Index

https://api.thehive.ai/api/v2/custom_index/remove/sync
https://api.thehive.ai/api/v2/custom_index/remove/async

Form Data

Field (*required)

Type

Description

url

String

Image url (publicly hosted media)

media

File

Image file (jpg, png, webp)

callback_url* (for async API requests)

String

Callback url where we will post Success/Failure response. Only required for async requests

Remove API Sample Response

//some fields truncated for clarity
{
  "status": {
    "code": "0",
    "message": "SUCCESS"
  },
  //truncated
    },
    "output": {
      "status": "Success",
      "id": "b2ff8040-a4a9-11ec-8936-9f134fd475df",
      "shaHash": "754766e29af5a241ab9192a69e2f74217802fbb50144d287905fe59c6fb40ce8",
      "message": "Image successfully removed from the index",
      "project_id": 32952
    }
  }
}