Independent Robotics

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 have it ready 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 especially 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 and object segmentation
  • Orthophoto search for objects of interest

Getting Started

Authentication

To start using the Insight Engine, 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.

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:

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

Creating a detector starts training it. Its status is "Training" while the model is being prepared, and the dashboard shows the percentage of training cycles completed and an estimated time remaining. Its status changes to "Ready" when it can run inference. If training is unsuccessful, its status changes to "Failed" and the dashboard shows the reason reported by the service.

While training, choose "Cancel training" and confirm to stop the run. The dashboard shows "Cancelling…" until training stops safely. Cancelling the first run leaves the detector "Failed" with a cancelled training outcome. Cancelling retraining keeps the previous successful model ready to use. Deleting a detector also requires confirmation; stop training before deleting it.

Running Object Detection

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

REST API Reference

Browse all available REST endpoints.

Detectors

9 operations

List Detectors

List detector metadata owned by the authenticated principal. Args: principal (Principal): Authenticated owner. service (DetectorService): Metadata service. Returns: list[DetectorResponse]: Detector metadata without model artifacts.

GET
/detectors

List Detectors

List detector metadata owned by the authenticated principal. Args: principal (Principal): Authenticated owner. service (DetectorService): Metadata service. Returns: list[DetectorResponse]: Detector metadata without model artifacts.

Responses

Successful Response

application/json
array

Fields

FieldTypeRequiredDescriptionNotes
items
object
Required
Detector metadata and the latest training state. Training parameters describe the last successful model, or the initial request if no training has succeeded. Pending overrides are not exposed.—
id
string (uuid)
Required
——
name
string
Required
——
description
anyOf
Optional
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
dataset_name
string
Required
——
resolution
string
Required
—enum: "coarse", "medium", "fine"
image_fit
anyOf
Optional
——
anyOf[1]
string
Optional
—enum: "pad", "crop"
anyOf[2]
null
Optional
——
epochs
integer
Required
——
state
string
Required
Stable states exposed by the version 0 HTTP contract.enum: "training", "ready", "failed"
failure_reason
anyOf
Required
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
training_progress
anyOf
Optional
Active-run epoch progress, or null when exact progress is unavailable.—
anyOf[1]
object
Optional
Epoch progress for the detector's active training run.—
completed_epochs
integer
Required
Epochs completed by the active run.—
total_epochs
integer
Required
Epochs requested for the active run.—
cancellation_requested
boolean
Optional
Cancellation accepted; waiting for the worker to stop.default: false
anyOf[2]
null
Optional
——
training_outcome
anyOf
Optional
Optional terminal detail. The stable state remains failed for cancelled or unrecognized stored training states.—
anyOf[1]
string
Optional
Optional detail for terminal states added after the version 0 contract.enum: "cancelled", "unknown"
anyOf[2]
null
Optional
——

Create Detector

Create a detector and schedule its initial training. Args: body (DetectorRequest): Initial name and training specification. principal (Principal): Authenticated owner. service (DetectorService): Detector creation service. Returns: DetectorResponse: Accepted detector in the training state.

POST
/detectors

Create Detector

Create a detector and schedule its initial training. Args: body (DetectorRequest): Initial name and training specification. principal (Principal): Authenticated owner. service (DetectorService): Detector creation service. Returns: DetectorResponse: Accepted detector in the training state.

Request body

Schema type: object

Fields

FieldTypeRequiredDescriptionNotes
name
string
Required
——
description
anyOf
Optional
Optional detector description.—
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
dataset_name
string
Required
——
resolution
string
Required
—enum: "coarse", "medium", "fine"
image_fit
string
Optional
—enum: "pad", "crop" · default: pad
epochs
integer
Required
——

Responses

Successful Response

application/json
object

Fields

FieldTypeRequiredDescriptionNotes
id
string (uuid)
Required
——
name
string
Required
——
description
anyOf
Optional
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
dataset_name
string
Required
——
resolution
string
Required
—enum: "coarse", "medium", "fine"
image_fit
anyOf
Optional
——
anyOf[1]
string
Optional
—enum: "pad", "crop"
anyOf[2]
null
Optional
——
epochs
integer
Required
——
state
string
Required
Stable states exposed by the version 0 HTTP contract.enum: "training", "ready", "failed"
failure_reason
anyOf
Required
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
training_progress
anyOf
Optional
Active-run epoch progress, or null when exact progress is unavailable.—
anyOf[1]
object
Optional
Epoch progress for the detector's active training run.—
completed_epochs
integer
Required
Epochs completed by the active run.—
total_epochs
integer
Required
Epochs requested for the active run.—
cancellation_requested
boolean
Optional
Cancellation accepted; waiting for the worker to stop.default: false
anyOf[2]
null
Optional
——
training_outcome
anyOf
Optional
Optional terminal detail. The stable state remains failed for cancelled or unrecognized stored training states.—
anyOf[1]
string
Optional
Optional detail for terminal states added after the version 0 contract.enum: "cancelled", "unknown"
anyOf[2]
null
Optional
——

Get Detector

Read one detector for display or lifecycle polling. Args: detector_id (UUID): Detector to read. principal (Principal): Authenticated owner. service (DetectorService): Metadata service. Returns: DetectorResponse: Stored parameters and current lifecycle state.

GET
/detectors/{detector_id}

Get Detector

Read one detector for display or lifecycle polling. Args: detector_id (UUID): Detector to read. principal (Principal): Authenticated owner. service (DetectorService): Metadata service. Returns: DetectorResponse: Stored parameters and current lifecycle state.

Parameters

NameInTypeRequiredDescription
detector_id
path
string
Required
—

Responses

Successful Response

application/json
object

Fields

FieldTypeRequiredDescriptionNotes
id
string (uuid)
Required
——
name
string
Required
——
description
anyOf
Optional
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
dataset_name
string
Required
——
resolution
string
Required
—enum: "coarse", "medium", "fine"
image_fit
anyOf
Optional
——
anyOf[1]
string
Optional
—enum: "pad", "crop"
anyOf[2]
null
Optional
——
epochs
integer
Required
——
state
string
Required
Stable states exposed by the version 0 HTTP contract.enum: "training", "ready", "failed"
failure_reason
anyOf
Required
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
training_progress
anyOf
Optional
Active-run epoch progress, or null when exact progress is unavailable.—
anyOf[1]
object
Optional
Epoch progress for the detector's active training run.—
completed_epochs
integer
Required
Epochs completed by the active run.—
total_epochs
integer
Required
Epochs requested for the active run.—
cancellation_requested
boolean
Optional
Cancellation accepted; waiting for the worker to stop.default: false
anyOf[2]
null
Optional
——
training_outcome
anyOf
Optional
Optional terminal detail. The stable state remains failed for cancelled or unrecognized stored training states.—
anyOf[1]
string
Optional
Optional detail for terminal states added after the version 0 contract.enum: "cancelled", "unknown"
anyOf[2]
null
Optional
——

Update Detector

Edit a detector's name or description without initiating training. Args: detector_id (UUID): Detector to update. body (UpdateDetectorRequest): Metadata fields to update; omitted fields are preserved. principal (Principal): Authenticated owner. service (DetectorService): Metadata service. Returns: DetectorResponse: Updated detector metadata.

PATCH
/detectors/{detector_id}

Update Detector

Edit a detector's name or description without initiating training. Args: detector_id (UUID): Detector to update. body (UpdateDetectorRequest): Metadata fields to update; omitted fields are preserved. principal (Principal): Authenticated owner. service (DetectorService): Metadata service. Returns: DetectorResponse: Updated detector metadata.

Parameters

NameInTypeRequiredDescription
detector_id
path
string
Required
—

Request body

Schema type: object

Fields

FieldTypeRequiredDescriptionNotes
name
string
Optional
Detector name. Omit to preserve the current value; null is not accepted.—
description
anyOf
Optional
Detector description. Omit to preserve the current value; null clears it.—
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——

Responses

Successful Response

application/json
object

Fields

FieldTypeRequiredDescriptionNotes
id
string (uuid)
Required
——
name
string
Required
——
description
anyOf
Optional
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
dataset_name
string
Required
——
resolution
string
Required
—enum: "coarse", "medium", "fine"
image_fit
anyOf
Optional
——
anyOf[1]
string
Optional
—enum: "pad", "crop"
anyOf[2]
null
Optional
——
epochs
integer
Required
——
state
string
Required
Stable states exposed by the version 0 HTTP contract.enum: "training", "ready", "failed"
failure_reason
anyOf
Required
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
training_progress
anyOf
Optional
Active-run epoch progress, or null when exact progress is unavailable.—
anyOf[1]
object
Optional
Epoch progress for the detector's active training run.—
completed_epochs
integer
Required
Epochs completed by the active run.—
total_epochs
integer
Required
Epochs requested for the active run.—
cancellation_requested
boolean
Optional
Cancellation accepted; waiting for the worker to stop.default: false
anyOf[2]
null
Optional
——
training_outcome
anyOf
Optional
Optional terminal detail. The stable state remains failed for cancelled or unrecognized stored training states.—
anyOf[1]
string
Optional
Optional detail for terminal states added after the version 0 contract.enum: "cancelled", "unknown"
anyOf[2]
null
Optional
——

Delete Detector

Delete a detector when no conflicting operation is active. Args: detector_id (UUID): Detector to delete. principal (Principal): Authenticated owner. service (DetectorService): Metadata service. Returns: Response: Empty success response.

DELETE
/detectors/{detector_id}

Delete Detector

Delete a detector when no conflicting operation is active. Args: detector_id (UUID): Detector to delete. principal (Principal): Authenticated owner. service (DetectorService): Metadata service. Returns: Response: Empty success response.

Parameters

NameInTypeRequiredDescription
detector_id
path
string
Required
—

Responses

Successful Response

Infer

Run a ready detector against a base64-encoded image. Args: detector_id (UUID): Detector to run. body (InferenceRequest): Image and score threshold. principal (Principal): Authenticated owner. service (InferenceService): Inference service. Returns: InferenceResponse: Thresholded boxes and unthresholded patch scores. Raises: HTTPException: If the detector is busy, unavailable, or the image is invalid.

POST
/detectors/{detector_id}/inference

Infer

Run a ready detector against a base64-encoded image. Args: detector_id (UUID): Detector to run. body (InferenceRequest): Image and score threshold. principal (Principal): Authenticated owner. service (InferenceService): Inference service. Returns: InferenceResponse: Thresholded boxes and unthresholded patch scores. Raises: HTTPException: If the detector is busy, unavailable, or the image is invalid.

Parameters

NameInTypeRequiredDescription
detector_id
path
string
Required
—

Request body

Schema type: object

Fields

FieldTypeRequiredDescriptionNotes
image
string (base64)
Required
Base64-encoded image file.—
threshold
number
Required
——

Responses

Successful Response

application/json
object

Fields

FieldTypeRequiredDescriptionNotes
bounding_boxes
array
Required
——
items
array
Required
——
patch_probability_grid
object
Required
Unthresholded patch scores positioned over the source image.—
scores
array
Required
Patch probabilities indexed by row, then column.—
items
array
Required
——
items
number
Required
——
image_size
object
Required
Image dimensions in source pixels.—
width
integer
Required
——
height
integer
Required
——
origin
object
Required
Top-left grid origin in source-image coordinates.—
x
number
Required
——
y
number
Required
——
stride
object
Required
Distance between adjacent patch boundaries in source pixels.—
x
number
Required
——
y
number
Required
——

Infer Multi Detector

Run several detectors while sharing embeddings for each resolution. The response contains one item per detector selection in request order. Duplicate detector IDs are allowed and may use different thresholds. Args: body (MultiDetectorInferenceRequest): Shared image and detector specifications. principal (Principal): Authenticated owner. service (InferenceService): Inference service. Returns: list[MultiDetectorInferenceResponse]: Detector results in request order. Raises: HTTPException: If the shared image is invalid or inference infrastructure fails.

POST
/detectors/inference/multi-detector

Infer Multi Detector

Run several detectors while sharing embeddings for each resolution. The response contains one item per detector selection in request order. Duplicate detector IDs are allowed and may use different thresholds. Args: body (MultiDetectorInferenceRequest): Shared image and detector specifications. principal (Principal): Authenticated owner. service (InferenceService): Inference service. Returns: list[MultiDetectorInferenceResponse]: Detector results in request order. Raises: HTTPException: If the shared image is invalid or inference infrastructure fails.

Request body

Schema type: object

Fields

FieldTypeRequiredDescriptionNotes
image
string (base64)
Required
Base64-encoded image file.—
detectors
array
Required
Ordered inference selections. Duplicate detector IDs are allowed; each selection produces one response using its own threshold.—
items
object
Required
One detector and its score threshold in a multi-detector request.—
detector_id
string (uuid)
Required
——
threshold
number
Required
——

Responses

Successful Response

application/json
array

Fields

FieldTypeRequiredDescriptionNotes
items
oneOf
Required
——
oneOf[1]
object
Optional
One detector's successful threshold-specific result.—
bounding_boxes
array
Required
——
items
array
Required
——
patch_probability_grid
object
Required
Unthresholded patch scores positioned over the source image.—
scores
array
Required
Patch probabilities indexed by row, then column.—
items
array
Required
——
items
number
Required
——
image_size
object
Required
Image dimensions in source pixels.—
width
integer
Required
——
height
integer
Required
——
origin
object
Required
Top-left grid origin in source-image coordinates.—
x
number
Required
——
y
number
Required
——
stride
object
Required
Distance between adjacent patch boundaries in source pixels.—
x
number
Required
——
y
number
Required
——
status
string
Optional
—default: succeeded
detector_id
string (uuid)
Required
——
threshold
number
Required
——
oneOf[2]
object
Optional
One detector's failed inference outcome.—
status
string
Optional
—default: failed
detector_id
string (uuid)
Required
——
threshold
number
Required
——
reason
string
Required
——

Retrain Detector

Request training with optional parameter overrides. Args: detector_id (UUID): Detector to retrain. body (RetrainingRequest): Overrides; an empty object reuses stored parameters. principal (Principal): Authenticated owner. service (DetectorService): Detector training service. Returns: DetectorResponse: Existing parameters with the training state. Raises: HTTPException: If an operation is active or a referenced resource is missing.

POST
/detectors/{detector_id}/training

Retrain Detector

Request training with optional parameter overrides. Args: detector_id (UUID): Detector to retrain. body (RetrainingRequest): Overrides; an empty object reuses stored parameters. principal (Principal): Authenticated owner. service (DetectorService): Detector training service. Returns: DetectorResponse: Existing parameters with the training state. Raises: HTTPException: If an operation is active or a referenced resource is missing.

Parameters

NameInTypeRequiredDescription
detector_id
path
string
Required
—

Request body

Schema type: object

Fields

FieldTypeRequiredDescriptionNotes
dataset_name
anyOf
Optional
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
resolution
anyOf
Optional
——
anyOf[1]
string
Optional
—enum: "coarse", "medium", "fine"
anyOf[2]
null
Optional
——
image_fit
anyOf
Optional
——
anyOf[1]
string
Optional
—enum: "pad", "crop"
anyOf[2]
null
Optional
——
epochs
anyOf
Optional
——
anyOf[1]
integer
Optional
——
anyOf[2]
null
Optional
——

Responses

Successful Response

application/json
object

Fields

FieldTypeRequiredDescriptionNotes
id
string (uuid)
Required
——
name
string
Required
——
description
anyOf
Optional
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
dataset_name
string
Required
——
resolution
string
Required
—enum: "coarse", "medium", "fine"
image_fit
anyOf
Optional
——
anyOf[1]
string
Optional
—enum: "pad", "crop"
anyOf[2]
null
Optional
——
epochs
integer
Required
——
state
string
Required
Stable states exposed by the version 0 HTTP contract.enum: "training", "ready", "failed"
failure_reason
anyOf
Required
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
training_progress
anyOf
Optional
Active-run epoch progress, or null when exact progress is unavailable.—
anyOf[1]
object
Optional
Epoch progress for the detector's active training run.—
completed_epochs
integer
Required
Epochs completed by the active run.—
total_epochs
integer
Required
Epochs requested for the active run.—
cancellation_requested
boolean
Optional
Cancellation accepted; waiting for the worker to stop.default: false
anyOf[2]
null
Optional
——
training_outcome
anyOf
Optional
Optional terminal detail. The stable state remains failed for cancelled or unrecognized stored training states.—
anyOf[1]
string
Optional
Optional detail for terminal states added after the version 0 contract.enum: "cancelled", "unknown"
anyOf[2]
null
Optional
——

Cancel Detector Training

Request cooperative cancellation of an active training run. The detector remains training until its worker stops. Cancellation preserves the last successful model. Without a previous model, it finishes in the failed state with a cancelled training outcome. Returns 409 when no run is active or its result is already being published.

POST
/detectors/{detector_id}/training/cancel

Cancel Detector Training

Request cooperative cancellation of an active training run. The detector remains training until its worker stops. Cancellation preserves the last successful model. Without a previous model, it finishes in the failed state with a cancelled training outcome. Returns 409 when no run is active or its result is already being published.

Parameters

NameInTypeRequiredDescription
detector_id
path
string
Required
—

Responses

Successful Response

application/json
object

Fields

FieldTypeRequiredDescriptionNotes
id
string (uuid)
Required
——
name
string
Required
——
description
anyOf
Optional
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
dataset_name
string
Required
——
resolution
string
Required
—enum: "coarse", "medium", "fine"
image_fit
anyOf
Optional
——
anyOf[1]
string
Optional
—enum: "pad", "crop"
anyOf[2]
null
Optional
——
epochs
integer
Required
——
state
string
Required
Stable states exposed by the version 0 HTTP contract.enum: "training", "ready", "failed"
failure_reason
anyOf
Required
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
training_progress
anyOf
Optional
Active-run epoch progress, or null when exact progress is unavailable.—
anyOf[1]
object
Optional
Epoch progress for the detector's active training run.—
completed_epochs
integer
Required
Epochs completed by the active run.—
total_epochs
integer
Required
Epochs requested for the active run.—
cancellation_requested
boolean
Optional
Cancellation accepted; waiting for the worker to stop.default: false
anyOf[2]
null
Optional
——
training_outcome
anyOf
Optional
Optional terminal detail. The stable state remains failed for cancelled or unrecognized stored training states.—
anyOf[1]
string
Optional
Optional detail for terminal states added after the version 0 contract.enum: "cancelled", "unknown"
anyOf[2]
null
Optional
——

Datasets

13 operations

List Datasets

List the caller's datasets with their currently usable examples. Args: principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: list[Dataset]: Datasets sorted by name.

GET
/datasets

List Datasets

List the caller's datasets with their currently usable examples. Args: principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: list[Dataset]: Datasets sorted by name.

Responses

Successful Response

application/json
array

Fields

FieldTypeRequiredDescriptionNotes
items
object
Required
——
name
string
Required
——
positives
array
Required
——
items
object
Required
——
image_key
string
Required
——
mask_key
string
Required
——
negatives
array
Required
——
items
string
Required
——
filenames
object
Required
——
sources
object
Optional
——
framings
object
Optional
——

Create Dataset

Create an empty dataset before uploading files. Args: body (CreateDatasetRequest): Dataset name. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Dataset: Newly created empty dataset.

POST
/datasets

Create Dataset

Create an empty dataset before uploading files. Args: body (CreateDatasetRequest): Dataset name. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Dataset: Newly created empty dataset.

Request body

Schema type: object

Fields

FieldTypeRequiredDescriptionNotes
name
string
Required
——

Responses

Successful Response

application/json
object

Fields

FieldTypeRequiredDescriptionNotes
name
string
Required
——
positives
array
Required
——
items
object
Required
——
image_key
string
Required
——
mask_key
string
Required
——
negatives
array
Required
——
items
string
Required
——
filenames
object
Required
——
sources
object
Optional
——
framings
object
Optional
——

Get Dataset

Read a dataset's complete examples and the filenames of all its files. Args: name (str): Dataset name. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Dataset: Currently usable positive pairs and negative images.

GET
/datasets/{name}

Get Dataset

Read a dataset's complete examples and the filenames of all its files. Args: name (str): Dataset name. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Dataset: Currently usable positive pairs and negative images.

Parameters

NameInTypeRequiredDescription
name
path
string
Required
—

Responses

Successful Response

application/json
object

Fields

FieldTypeRequiredDescriptionNotes
name
string
Required
——
positives
array
Required
——
items
object
Required
——
image_key
string
Required
——
mask_key
string
Required
——
negatives
array
Required
——
items
string
Required
——
filenames
object
Required
——
sources
object
Optional
——
framings
object
Optional
——

Delete Dataset

Delete a dataset and all its files; repeated deletion is harmless. Args: name (str): Dataset name. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

DELETE
/datasets/{name}

Delete Dataset

Delete a dataset and all its files; repeated deletion is harmless. Args: name (str): Dataset name. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

Parameters

NameInTypeRequiredDescription
name
path
string
Required
—

Responses

Successful Response

Allocate Upload

Allocate a new file key and prepare its PUT upload. Every call allocates a distinct key, so files may share a filename. Use the returned key wherever a file key is expected. Upload the bytes before registering membership; allocation does not add an example. Args: name (str): Existing dataset name. body (AllocateUploadRequest): Display filename. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: AllocatedUpload: Allocated key, filename, and upload URL.

POST
/datasets/{name}/files/upload-url

Allocate Upload

Allocate a new file key and prepare its PUT upload. Every call allocates a distinct key, so files may share a filename. Use the returned key wherever a file key is expected. Upload the bytes before registering membership; allocation does not add an example. Args: name (str): Existing dataset name. body (AllocateUploadRequest): Display filename. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: AllocatedUpload: Allocated key, filename, and upload URL.

Parameters

NameInTypeRequiredDescription
name
path
string
Required
—

Request body

Schema type: object

Fields

FieldTypeRequiredDescriptionNotes
filename
string
Required
——
source_key
anyOf
Optional
——
anyOf[1]
string
Optional
——
anyOf[2]
null
Optional
——
framing
anyOf
Optional
——
anyOf[1]
object
Optional
Aspect-preserving square-frame placement applied to a source image.—
fit
string
Required
—enum: "pad", "crop"
focus_x
number
Optional
—default: 0.5
focus_y
number
Optional
—default: 0.5
zoom
number
Optional
—default: 1
reviewed
boolean
Optional
—default: false
anyOf[2]
null
Optional
——

Responses

Successful Response

application/json
object

Fields

FieldTypeRequiredDescriptionNotes
key
string
Required
——
filename
string
Required
——
url
string
Required
——

Prepare Upload

Prepare a PUT upload to a caller-chosen key, which may replace its file. Upload the bytes to the returned URL before registering membership. Preparing an upload does not add a positive or negative example. Args: name (str): Existing dataset name. key (str): Dataset-local file key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: PresignedUrlResponse: URL accepting the file bytes via PUT.

POST
/datasets/{name}/files/{key}/upload-url

Prepare Upload

Prepare a PUT upload to a caller-chosen key, which may replace its file. Upload the bytes to the returned URL before registering membership. Preparing an upload does not add a positive or negative example. Args: name (str): Existing dataset name. key (str): Dataset-local file key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: PresignedUrlResponse: URL accepting the file bytes via PUT.

Parameters

NameInTypeRequiredDescription
name
path
string
Required
—
key
path
string
Required
—

Responses

Successful Response

application/json
object

Fields

FieldTypeRequiredDescriptionNotes
url
string
Required
——

Prepare Download

Prepare a GET download for an existing file. Args: name (str): Dataset name. key (str): Dataset-local file key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: PresignedUrlResponse: URL returning file bytes via GET.

POST
/datasets/{name}/files/{key}/download-url

Prepare Download

Prepare a GET download for an existing file. Args: name (str): Dataset name. key (str): Dataset-local file key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: PresignedUrlResponse: URL returning file bytes via GET.

Parameters

NameInTypeRequiredDescription
name
path
string
Required
—
key
path
string
Required
—

Responses

Successful Response

application/json
object

Fields

FieldTypeRequiredDescriptionNotes
url
string
Required
——

Add Positive

Register an uploaded image-mask pair; repeating the same pair is harmless. Either file may also belong to other pairs or be a negative image. Args: name (str): Dataset name. image_key (str): Uploaded positive image key. body (PositivePairRequest): Uploaded mask key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

PUT
/datasets/{name}/positives/{image_key}

Add Positive

Register an uploaded image-mask pair; repeating the same pair is harmless. Either file may also belong to other pairs or be a negative image. Args: name (str): Dataset name. image_key (str): Uploaded positive image key. body (PositivePairRequest): Uploaded mask key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

Parameters

NameInTypeRequiredDescription
name
path
string
Required
—
image_key
path
string
Required
—

Request body

Schema type: object

Fields

FieldTypeRequiredDescriptionNotes
mask_key
string
Required
——

Responses

Successful Response

Remove Positive

Remove an image and all its masks from the positives, keeping every file. Returns 204 even if the image has no registered pairs, so retries are safe. Args: name (str): Dataset name. image_key (str): Positive image key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

DELETE
/datasets/{name}/positives/{image_key}

Remove Positive

Remove an image and all its masks from the positives, keeping every file. Returns 204 even if the image has no registered pairs, so retries are safe. Args: name (str): Dataset name. image_key (str): Positive image key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

Parameters

NameInTypeRequiredDescription
name
path
string
Required
—
image_key
path
string
Required
—

Responses

Successful Response

Add Negative

Register an uploaded negative image; repeating the same addition is harmless. The file may also belong to positive pairs. Args: name (str): Dataset name. image_key (str): Uploaded negative image key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

PUT
/datasets/{name}/negatives/{image_key}

Add Negative

Register an uploaded negative image; repeating the same addition is harmless. The file may also belong to positive pairs. Args: name (str): Dataset name. image_key (str): Uploaded negative image key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

Parameters

NameInTypeRequiredDescription
name
path
string
Required
—
image_key
path
string
Required
—

Responses

Successful Response

Remove Negative

Remove a negative image from the dataset's examples, keeping its file. Returns 204 even if the image is not registered as a negative, so retries are safe. Args: name (str): Dataset name. image_key (str): Negative image key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

DELETE
/datasets/{name}/negatives/{image_key}

Remove Negative

Remove a negative image from the dataset's examples, keeping its file. Returns 204 even if the image is not registered as a negative, so retries are safe. Args: name (str): Dataset name. image_key (str): Negative image key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

Parameters

NameInTypeRequiredDescription
name
path
string
Required
—
image_key
path
string
Required
—

Responses

Successful Response

Remove Positive Pair

Remove one image-mask pair from the positives, keeping both files. The image's other pairs are unaffected. Returns 204 even if the pair is not registered, so retries are safe. Args: name (str): Dataset name. image_key (str): Positive image key. mask_key (str): Key of the mask whose pair to remove. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

DELETE
/datasets/{name}/positives/{image_key}/masks/{mask_key}

Remove Positive Pair

Remove one image-mask pair from the positives, keeping both files. The image's other pairs are unaffected. Returns 204 even if the pair is not registered, so retries are safe. Args: name (str): Dataset name. image_key (str): Positive image key. mask_key (str): Key of the mask whose pair to remove. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

Parameters

NameInTypeRequiredDescription
name
path
string
Required
—
image_key
path
string
Required
—
mask_key
path
string
Required
—

Responses

Successful Response

Delete Image

Delete a file and every example using it; repeated deletion is harmless. Deleting also removes the file from every example. If the file is the image of a positive pair, that pair's mask is deleted too, unless another example still uses it. Deleting a mask or negative deletes no other file; images left without examples remain uploaded. To keep the file, remove the example instead. Args: name (str): Dataset name. key (str): Dataset-local file key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

DELETE
/datasets/{name}/files/{key}

Delete Image

Delete a file and every example using it; repeated deletion is harmless. Deleting also removes the file from every example. If the file is the image of a positive pair, that pair's mask is deleted too, unless another example still uses it. Deleting a mask or negative deletes no other file; images left without examples remain uploaded. To keep the file, remove the example instead. Args: name (str): Dataset name. key (str): Dataset-local file key. principal (Principal): Authenticated owner. repository (DatasetRepository): Dataset persistence. Returns: Response: Empty success response.

Parameters

NameInTypeRequiredDescription
name
path
string
Required
—
key
path
string
Required
—

Responses

Successful Response

Segmentation

1 operation

Segment From Points

Segment an image using positive and negative points. Args: body (SegmentationRequest): Image bytes and point prompts. service (SegmentationService): Application-owned segmentation service. Returns: Response: Highest-scoring mask as a grayscale PNG.

POST
/segment/from_points

Segment From Points

Segment an image using positive and negative points. Args: body (SegmentationRequest): Image bytes and point prompts. service (SegmentationService): Application-owned segmentation service. Returns: Response: Highest-scoring mask as a grayscale PNG.

Request body

Schema type: object

Fields

FieldTypeRequiredDescriptionNotes
image
string (base64)
Required
Base64-encoded image file.—
positives
array
Required
——
items
object
Required
A pixel coordinate in the source image.—
x
integer
Required
——
y
integer
Required
——
negatives
array
Optional
——
items
object
Required
A pixel coordinate in the source image.—
x
integer
Required
——
y
integer
Required
——

Responses

PNG image containing the highest-scoring mask.

image/png
string

Fields

FieldTypeRequiredDescriptionNotes
value
string (binary)
Required
——