Insight Engine Documentation

Getting started guides and API reference

Why use the Insight Engine

The Insight Engine creates visual object detectors from only a few images which means you can get up and running with your project without the need to train your own vision model.

Given a few example images, you can quickly create a detector and deploy it within minutes, giving you the ability to leverage vision AI on your specialized task right away.

Use cases

The Insight Engine is a flexible tool at your disposal to solve your visual detection needs. It's specially useful if you face:

rapidly changing detection demands
need to detect a specialized or uncommon object
want to rapidly prototype

Common use cases from our partners include:

Rapid prototyping of a new vision capability
Data annotation, object segmentaiton
Orthophoto search for objects of interest

Heads up!

If you have used the Insight Engine for another use case, we'd like to hear from you!

Getting Started

Authentication

To start using the InsightEngine, you'll first have to create an account and then login. Once logged in, you can generate an API key from your dashboard by clicking the "create API key" button.

Important Security Notice

It is important to keep your API key secure and NEVER share it. Leaked API keys may compromise your account!

To use your API key, you must supply it in the "x-api-key" header when making requests to our REST API.

Creating Your First Detector

To create your first detector, visit the detectors page and click on the "create detector" button. Alternatively, you can make use of our API endpoint (see below). We recommend you use the dashboard.

To create a detector, you will need:

A name for your detector
A few example images of what you'd like to detect
Masks for your positive examples. Note that this is seamless on our dashboard GUI using our built-in segmentation tool.

Once you have created your first detector, you will see that it is in a state of "Not Deployed". In order to start using your detector, you must deploy it. You can achieve this on your dashboard using the "deploy" button or programatically using the API endpoint (see below). Once the deployment is successful, you will see a "Deployed" status next to your detector. This indicates that it is ready to be used.

Heads up!

You can also edit your detector by uploading/removing examples or by tweaking its properties. Note however, that doing this will put your detector in a "Stale" state, and requires redeployment!

Running Object Detection

You can use your detectors for inference through the dashboard or through our REST API using the "/detector/infer" endpoint. We recommend testing the detector using the dashboard but running large jobs on many images using the API.

Orthophoto (GIS) Search

You can use detectors to search for instances of objects on large scale aerial photography (orthophotos) such as satellite or drone imagery. We currently support common image formats such as (.jpeg and .png) as well as geotiffs (.tiff).

REST API Reference

Browse all available REST endpoints.

Segmentation

Interactive segmentation utilities.

1 operation

Segment from points

Use a collection of positive and negative points to segment an image. Used in creating masks for detectors.

POST

/segment/from_points

Segment from points

Use a collection of positive and negative points to segment an image. Used in creating masks for detectors.

Request body

Schema type: object

Fields

Field	Type	Required	Description	Notes
file	string (binary)	Required	—	—
positives	string	Optional	—	default: []
negatives	string	Optional	—	default: []

Responses

PNG image stream containing the generated mask.

image/png

string

Fields

Field	Type	Required	Description	Notes
value	string (binary)	Required	—	—

Detector Management

9 operations

Deploy detector

Deploy a detector for use. Any new or edited/updated detector must be deployed.

POST

/detectors/users/detectors/{detector_id}/deploy

Deploy detector

Deploy a detector for use. Any new or edited/updated detector must be deployed.

Parameters

Name	In	Type	Required	Description
detector_id	path	string	Required	—

Responses

Succesfully started deploying detector.

application/json

payload

Fields

Field	Type	Required	Description	Notes
value	unknown	Required	—	—

Single image detector inference

Runs inference using a stored detector on a single image and returns the rendered detection overlay as PNG.

POST

/detectors/users/detectors/{detector_id}/infer

Single image detector inference

Runs inference using a stored detector on a single image and returns the rendered detection overlay as PNG.

Parameters

Name	In	Type	Required	Description
detector_id	path	string	Required	—

Request body

Schema type: object

Fields

Field	Type	Required	Description	Notes
file	string (binary)	Required	Image to run inference on.	—

Responses

PNG image containing detector output.

application/json

payload

Fields

Field	Type	Required	Description	Notes
value	unknown	Required	—	—

Single image detector inference (data outputs)

Runs inference using a stored detector on a single image and returns either logits or bounding boxes as JSON.

POST

/detectors/users/detectors/{detector_id}/infer-detailed

Single image detector inference (data outputs)

Runs inference using a stored detector on a single image and returns either logits or bounding boxes as JSON.

Parameters

Name	In	Type	Required	Description
detector_id	path	string	Required	—

Request body

Schema type: object

Fields

Field	Type	Required	Description	Notes
file	string (binary)	Required	Image to run inference on.	—
threshold	number	Required	Detection confidence threshold applied to results before returning (0-1).	—

Responses

JSON payload containing requested detector data (logits or bounding boxes).

application/json

payload

Fields

Field	Type	Required	Description	Notes
value	unknown	Required	—	—

Tiled detector inference

Runs tiled inference with optional refinement parameters and returns a multipart stream containing the visualization and logits metadata.

POST

/detectors/users/detectors/{detector_id}/infer_tiled

Tiled detector inference

Runs tiled inference with optional refinement parameters and returns a multipart stream containing the visualization and logits metadata.

Parameters

Name	In	Type	Required	Description
detector_id	path	string	Required	—

Request body

Schema type: object

Fields

Field	Type	Required	Description	Notes
file	string (binary)	Required	Image to run inference on.	—
tile_size	integer	Required	Tile size provided by user from the frontend.	—
sample_tiles	integer	Required	The number of tiles to grab for refinement.	—
refinement_epochs	integer	Required	Epochs to iterate over refinement tiles.	—
remembering_epochs	integer	Required	Epochs to iterate over real examples (remembering).	—
threshold	integer	Required	Detection threshold as integer 1-100; converted to 0-1 by the service.	—
display_logits	boolean	Required	Whether to include logits/visualization images in the multipart response.	—
blur_sigma	integer	Required	Sigma value for Gaussian blur applied to tiles during processing.	—
min_patch_size	integer	Required	Minimum number of patches required for a valid detection cluster.	—
merge_refinement	boolean	Required	Whether to merge refinement and remembering training steps during on-the-fly refinement.	—

Responses

Multipart response containing inference imagery and JSON metadata.

application/json

payload

Fields

Field	Type	Required	Description	Notes
value	unknown	Required	—	—

List detectors

Return a list of available detectors and their associated metadata.

GET

/detectors/users/detectors

List detectors

Return a list of available detectors and their associated metadata.

Responses

Array of detector metadata objects owned by the caller.

application/json

array

Fields

Field	Type	Required	Description	Notes
items	object	Required	—	—

Delete a detector

Removes the detector's stored artifacts (metadata, models, imagery).

DELETE

/detectors/users/detectors/{detector_id}/delete

Delete a detector

Removes the detector's stored artifacts (metadata, models, imagery).

Parameters

Name	In	Type	Required	Description
detector_id	path	string	Required	—

Responses

Successful Response

application/json

payload

Fields

Field	Type	Required	Description	Notes
value	unknown	Required	—	—

Save detector configuration

Uploads detector training assets (queries, masks, negatives) and persists metadata. Marks detectors stale when critical parameters change.

POST

/detectors/users/detectors/save

Save detector configuration

Uploads detector training assets (queries, masks, negatives) and persists metadata. Marks detectors stale when critical parameters change.

Request body

Schema type: object

Fields

Field	Type	Required	Description	Notes
detector_name	string	Required	—	—
detector_resolution	string	Required	—	—
epochs	integer	Required	—	—
positives	array	Required	List of positive example files	—
items	string (binary)	Required	—	—
positive_masks	array	Required	List of positive mask files aligned with positives	—
items	string (binary)	Required	—	—
negatives	anyOf	Optional	Optional list of negative example files	—
anyOf[1]	array	Optional	—	—
items	string (binary)	Required	—	—
anyOf[2]	null	Optional	—	—
detector_id	anyOf	Optional	—	—
anyOf[1]	string	Optional	—	—
anyOf[2]	null	Optional	—	—

Responses

Detector assets stored and metadata updated.

application/json

object

Fetch detector metadata

Returns the metadata associated with a detector.

GET

/detectors/users/detectors/{detector_id}/metadata

Fetch detector metadata

Returns the metadata associated with a detector.

Parameters

Name	In	Type	Required	Description
detector_id	path	string	Required	—

Responses

Detector metadata payload.

application/json

object

Fetch detector image asset

Streams a thumbnail-sized detector asset image stored in Azure.

GET

/detectors/users/detectors/{detector_id}/images/{image_id}

Fetch detector image asset

Streams a thumbnail-sized detector asset image stored in Azure.

Parameters

Name	In	Type	Required	Description
detector_id	path	string	Required	—
image_id	path	string	Required	—

Responses

WEBP image stream representing the detector asset.

application/json

payload

Fields

Field	Type	Required	Description	Notes
value	unknown	Required	—	—