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>').
NOTE: The API keys to authenticate tasks is the same for all three endpoints (add, query, remove). Use the API Key associated with the "Add" Endpoint.

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

NOTE: Querying an image will not automatically add it to the index. You must add the image manually using the "Add" Endpoint.

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
task_id	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
    }
  }
}