Documentation
Ask or search…
K

API

The API is available at https://api.segments.ai/.
To authenticate, add an API key in the header of each request:
curl -H "Authorization: APIKey YOUR_API_KEY"
An API key can be created on your user account page.

Datasets

List datasets

GET /users/:owner/datasets
To get all datasets of the currently logged in users, you can use this shortcut:
GET /user/datasets
Note that this will only return datasets which are public, and datasets which are private but where the logged in user is a collaborator.

Response

Status: 200 OK
[
{
"name": "cats",
"description": "A dataset of cat images.",
"data_type": "IMAGE",
"category": "other",
"public": false,
"owner": {
"username": "bert",
"email": "[email protected]",
"created_at": "2020-05-11T14:00:53.763278Z"
},
"created_at": "2020-04-10T20:09:31Z",
"collaborators_count": 0,
"samples_count": 94
}
]

Get a dataset

GET /datasets/:owner/:dataset

Response

Status: 200 OK
{
"name": "cats",
"description": "A dataset of cat images.",
"category": "other",
"public": false,
"owner": {
"username": "bert",
"created_at": "2020-05-11T14:00:53.763278Z"
},
"created_at": "2020-07-20T14:59:36.242218Z",
"collaborators_count": 0,
"samples_count": 94,
"task_type": "segmentation-bitmap",
"task_attributes": {
"format_version": "0.1",
"categories": [
{
"name": "cat",
"id": 0
},
{
"name": "dog",
"id": 1
}
]
},
"labelsets": [
{
"name": "ground-truth",
"description": "Ground truth labels.",
},
{
"name": "predictions",
"description": "My model predictions.",
},
]
}

Create a dataset

POST /user/datasets

Input

Name
Type
Description
name
string
Required. The name of the dataset.
description
string
The description of the dataset.
task_type
string
The task type of the dataset. Can be one of:
  • segmentation-bitmap: Semantic, panoptic and instance segmentation.
  • vector: Polygons, polylines, bounding boxes, points.
  • bboxes: Bounding boxes only.
task_attributes
dict
The task attributes. See Configuring the label editor.
category
string
Category of the data.
public
boolean
Sets the visibility of a dataset. Can be one of:
  • true - Anyone can see the dataset.
  • false - Only the owner and collaborators can view the dataset.
readme
string
The readme of the dataset, displayed on the overview tab.
enable_skip_labeling
boolean
Enable the skip button in the labeling workflow. Defaults to True.
enable_skip_reviewing
boolean
Enable the skip button in the reviewing workflow. Defaults to False.
enable_ratings
boolean
Enable star-ratings for labeled images. Defaults to False.

Example

{
"name": "cats",
"description": "A dataset of cat images."
}

Response

Status: 201 Created
{
"name": "cats",
"description": "A dataset of cat images.",
"category": "other",
"public": false,
"owner": {
"username": "bert",
"email": "[email protected]",
"created_at": "2020-05-11T14:00:53.763278Z"
},
"created_at": "2020-07-20T14:59:36.242218Z",
"collaborators_count": 0,
"samples_count": 94
}

Update a dataset

PATCH /datasets/:owner/:dataset
Same fields as previous.

Delete a dataset

DELETE /datasets/:owner/:dataset

Add a collaborator to a dataset

POST /datasets/:owner/:dataset/collaborators

Input

Name
Type
Description
user
string
Required. The username of the collaborator to be added.
role
string
The role of the collaborator. Can be one of: labeler, reviewer, admin

Example

{
"user": "jane",
"role": "reviewer"
}

Response

Status: 201 Created
{
"user": "jane",
"role": "reviewer"
}

Samples

List samples

GET /datasets/:owner/:dataset/samples

Response

Status: 200 OK
[
{
"uuid": "10130ecd-790e-463d-86ce-747f5c545c77",
"name": "image.png"
"data_type": "IMAGE",
"attributes": {
"image": {"url": "https://example.com/image.png"}
},
"metadata": {},
"priority": 0,
"created_at": "2011-04-10T20:09:31Z"
"created_by": "jane"
}
]

Get a sample

GET /samples/:sample_uuid

Response

Status: 200 OK
{
"uuid": "10130ecd-790e-463d-86ce-747f5c545c77",
"name": "image.png"
"data_type": "IMAGE",
"attributes": {
"image": {"url": "https://example.com/image.png"}
},
"metadata": {}
"priority": 0,
"created_at": "2020-04-10T20:09:31Z"
"created_by": "jane",
"dataset": "jane/cats"
}

Create a sample

POST /datasets/:owner/:dataset/samples

Input

Name
Type
Description
name
string
Required. The name of the sample.
attributes
object
Sample data.
metadata
object
User-defined metadata.
priority
float
Priority in the labeling queue. Samples with higher values will be labeled first. Default is 0.

Example

{
"name": "flowers.png",
"attributes": {
"image": {
"url": "https://example.com/image.png"
}
},
"metadata": {
"city": "London",
"weather": "cloudy",
"robot_id": 3
},
"priority": 10
}

Response

Status: 201 Created
{
"uuid": "10130ecd-790e-463d-86ce-747f5c545c77",
"name": "image.png"
"data_type": "IMAGE",
"attributes": {
"image": {
"url": "https://example.com/image.png"
}
},
"metadata": {
"city": "London",
"weather": "cloudy",
"robot_id": 3
},
"priority": 10,
"created_at": "2011-04-10T20:09:31Z"
"created_by": "jane"
}

Update a sample

PATCH /samples/:sample_uuid
Same fields as previous.

Delete a sample

DELETE /samples/:sample_uuid

Labels

Get a label

GET /labels/:sample_uuid/:labelset

Response

Status: 200 OK
{
"label_type": "segmentation-bitmap",
"label_status": "LABELED",
"attributes": {
"format_version": "0.1",
"annotations": [
{
"id": 1,
"category_id": 0
}
],
"segmentation_bitmap": {
"url": "https://segmentsai-staging.s3.eu-west-2.amazonaws.com/assets/davy/ddf55e99-1a6f-42d2-83e9-8657de3259a1.png"
}
},
"created_at": "2020-04-10T20:09:31Z",
"created_by": "jane",
}

Create or update a label

PUT /labels/:sample_uuid/:labelset

Input

Name
Type
Description
attributes
object
Label data. Format depends on the label type, see label formats.
label_status
string
Status of the label.
Can be one of: LABELED, REVIEWED, REJECTED, PRELABELED, SKIPPED
score
float
Prediction score.

Example

{
"attributes": {
"format_version": "0.1",
"annotations": [
{
"id": 1,
"category_id": 0,
}
],
"segmentation_bitmap": {
"url": "https://example.com/label.png"
}
},
"label_status": "PRELABELED",
"score": 0.9254
}

Response

Status: 201 Created
{
"attributes": {
"format_version": "0.1",
"annotations": [
{
"id": 1,
"category_id": 0,
}
],
"segmentation_bitmap": {
"url": "https://example.com/label.png"
}
},
"label_status": "PRELABELED",
"created_at": "2011-04-10T20:09:31Z"
}

Delete a label

DELETE /labels/:sample_uuid/:labelset

Releases

List releases

GET /datasets/:owner/:dataset/releases

Response

Status: 200 OK
[
{
"name": "v0.1",
"description": "My first release.",
"attributes": {
"url": "https://segmentsai-prod.s3.eu-west-2.amazonaws.com/releases/f0b0a34b-93ca-41a3-06ee-96ce6436dd41.json"
},
"status": "SUCCEEDED",
"created_at": "2020-07-20T14:59:36.242218Z"
}
]

Get a release

GET /datasets/:owner/:dataset/releases/:release_name

Response

Status: 200 OK
{
"name": "v0.1",
"description": "My first release.",
"attributes": {
"url": "https://segmentsai-prod.s3.eu-west-2.amazonaws.com/releases/f0b0a34b-93ca-41a3-06ee-96ce6436dd41.json"
},
"status": "SUCCEEDED",
"created_at": "2020-07-20T14:59:36.242218Z"
}

Create a release

POST /datasets/:owner/:dataset/releases

Input

Name
Type
Description
name
string
Required. The name of the release.
description
string
The description of the release.

Example

{
"name": "v0.1",
"description": "My first release."
}

Response

Status: 201 Created
{
"name": "v0.1",
"description": "My first release.",
"status": "PENDING",
"created_at": "2020-07-20T14:59:36.242218Z"
}

Delete a release

DELETE /datasets/:owner/:dataset/releases/:release_name