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:
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
[
{
"name": "cats",
"description": "A dataset of cat images.",
"data_type": "IMAGE",
"category": "other",
"public": false,
"owner": {
"username": "bert",
"email": "bert@segments.ai",
"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
{
"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
Input
Required. The name of the dataset.
The description of the dataset.
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.
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.
The readme of the dataset, displayed on the overview tab.
Enable the skip button in the labeling workflow. Defaults to True.
Enable the skip button in the reviewing workflow. Defaults to False.
Enable star-ratings for labeled images. Defaults to False.
Example
{
"name": "cats",
"description": "A dataset of cat images."
}
Response
{
"name": "cats",
"description": "A dataset of cat images.",
"category": "other",
"public": false,
"owner": {
"username": "bert",
"email": "bert@segments.ai",
"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
Required. The username of the collaborator to be added.
The role of the collaborator. Can be one of: labeler, reviewer, admin
Example
{
"user": "jane",
"role": "reviewer"
}
Response
{
"user": "jane",
"role": "reviewer"
}
Samples
List samples
GET /datasets/:owner/:dataset/samples
Response
[
{
"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
{
"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
Required. The name of the sample.
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
{
"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
{
"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
Status of the label.
Can be one of: LABELED, REVIEWED, REJECTED, PRELABELED, SKIPPED
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
{
"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
[
{
"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
{
"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
Required. The name of the release.
The description of the release.
Example
{
"name": "v0.1",
"description": "My first release."
}
Response
{
"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
Last updated
