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/Video url (publicly hosted media)
media	File	Image/Video 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"
            },
            "output": {
                "message": "Media 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/Video url (publicly hosted media)
media	File	Image/Video 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": [
        {
          "task_id": "c20519a0-3f6e-11ed-b689-498949850c8a",
          "metadata": "",
          "matches": [
            {
              "query_timestamp": 2.9696333333333333,
              "matching_timestamp": 2.9696333333333333,
              "similarity_score": 0.99
            },
            {
              "query_timestamp": 3.9706333333333332,
              "matching_timestamp": 3.9706333333333332,
              "similarity_score": 1
            },
            {
              "query_timestamp": 4.971633333333333,
              "matching_timestamp": 4.971633333333333,
              "similarity_score": 1
            },
            {
              "query_timestamp": 5.9726333333333335,
              "matching_timestamp": 5.9726333333333335,
              "similarity_score": 0.98
            },
            {
              "query_timestamp": 6.973633333333334,
              "matching_timestamp": 6.973633333333334,
              "similarity_score": 1
            }
          ]
        },
        {
          "task_id": "8eb655a0-3f6e-11ed-b689-498949850c8a",
          "metadata": "",
          "matches": [
            {
              "query_timestamp": 0,
              "matching_timestamp": 0,
              "similarity_score": 1
            },
            {
              "query_timestamp": 0.9676333333333333,
              "matching_timestamp": 0.9676333333333333,
              "similarity_score": 1
            },
            ...
          ]
        }             
      ]
    }
}

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
text_data	String	Task-ID of the object to remove from index
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",
          "message": "Media successfully removed from the index"
  }
}