Custom Search

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"
            },
            "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 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
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",
      "id": "b2ff8040-a4a9-11ec-8936-9f134fd475df",
      "shaHash": "754766e29af5a241ab9192a69e2f74217802fbb50144d287905fe59c6fb40ce8",
      "message": "Media successfully removed from the index",
      "project_id": 32952
    }
  }
}