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

Datasets

List datasets

1
GET /users/:owner/datasets
Copied!
To get all datasets of the currently logged in users, you can use this shortcut:
1
GET /user/datasets
Copied!
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
1
[
2
{
3
"name": "cats",
4
"description": "A dataset of cat images.",
5
"data_type": "IMAGE",
6
"category": "other",
7
"public": false,
8
"owner": {
9
"username": "bert",
10
"email": "[email protected]",
11
"created_at": "2020-05-11T14:00:53.763278Z"
12
},
13
"created_at": "2020-04-10T20:09:31Z",
14
"collaborators_count": 0,
15
"samples_count": 94
16
}
17
]
Copied!

Get a dataset

1
GET /datasets/:owner/:dataset
Copied!

Response

Status: 200 OK
1
{
2
"name": "cats",
3
"description": "A dataset of cat images.",
4
"category": "other",
5
"public": false,
6
"owner": {
7
"username": "bert",
8
"created_at": "2020-05-11T14:00:53.763278Z"
9
},
10
"created_at": "2020-07-20T14:59:36.242218Z",
11
"collaborators_count": 0,
12
"samples_count": 94,
13
"task_type": "segmentation-bitmap",
14
"task_attributes": {
15
"format_version": "0.1",
16
"categories": [
17
{
18
"name": "cat",
19
"id": 0
20
},
21
{
22
"name": "dog",
23
"id": 1
24
}
25
]
26
},
27
"labelsets": [
28
{
29
"name": "ground-truth",
30
"description": "Ground truth labels.",
31
},
32
{
33
"name": "predictions",
34
"description": "My model predictions.",
35
},
36
]
37
}
Copied!

Create a dataset

1
POST /user/datasets
Copied!

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.

Example

1
{
2
"name": "cats",
3
"description": "A dataset of cat images."
4
}
Copied!

Response

Status: 201 Created
1
{
2
"name": "cats",
3
"description": "A dataset of cat images.",
4
"category": "other",
5
"public": false,
6
"owner": {
7
"username": "bert",
8
"email": "[email protected]",
9
"created_at": "2020-05-11T14:00:53.763278Z"
10
},
11
"created_at": "2020-07-20T14:59:36.242218Z",
12
"collaborators_count": 0,
13
"samples_count": 94
14
}
Copied!

Update a dataset

1
PATCH /datasets/:owner/:dataset
Copied!
Same fields as previous.

Delete a dataset

1
DELETE /datasets/:owner/:dataset
Copied!

Add a collaborator to a dataset

1
POST /datasets/:owner/:dataset/collaborators
Copied!

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

1
{
2
"user": "jane",
3
"role": "reviewer"
4
}
Copied!

Response

Status: 201 Created
1
{
2
"user": "jane",
3
"role": "reviewer"
4
}
Copied!

Samples

List samples

1
GET /datasets/:owner/:dataset/samples
Copied!

Response

Status: 200 OK
1
[
2
{
3
"uuid": "10130ecd-790e-463d-86ce-747f5c545c77",
4
"name": "image.png"
5
"data_type": "IMAGE",
6
"attributes": {
7
"image": {"url": "https://example.com/image.png"}
8
},
9
"metadata": {},
10
"priority": 0,
11
"created_at": "2011-04-10T20:09:31Z"
12
"created_by": "jane"
13
}
14
]
Copied!

Get a sample

1
GET /samples/:sample_uuid
Copied!

Response

Status: 200 OK
1
{
2
"uuid": "10130ecd-790e-463d-86ce-747f5c545c77",
3
"name": "image.png"
4
"data_type": "IMAGE",
5
"attributes": {
6
"image": {"url": "https://example.com/image.png"}
7
},
8
"metadata": {}
9
"priority": 0,
10
"created_at": "2020-04-10T20:09:31Z"
11
"created_by": "jane",
12
"dataset": "jane/cats"
13
}
Copied!

Create a sample

1
POST /datasets/:owner/:dataset/samples
Copied!

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

1
{
2
"name": "flowers.png",
3
"attributes": {
4
"image": {
5
"url": "https://example.com/image.png"
6
}
7
},
8
"metadata": {
9
"city": "London",
10
"weather": "cloudy",
11
"robot_id": 3
12
},
13
"priority": 10
14
}
Copied!

Response

Status: 201 Created
1
{
2
"uuid": "10130ecd-790e-463d-86ce-747f5c545c77",
3
"name": "image.png"
4
"data_type": "IMAGE",
5
"attributes": {
6
"image": {
7
"url": "https://example.com/image.png"
8
}
9
},
10
"metadata": {
11
"city": "London",
12
"weather": "cloudy",
13
"robot_id": 3
14
},
15
"priority": 10,
16
"created_at": "2011-04-10T20:09:31Z"
17
"created_by": "jane"
18
}
Copied!

Update a sample

1
PATCH /samples/:sample_uuid
Copied!
Same fields as previous.

Delete a sample

1
DELETE /samples/:sample_uuid
Copied!

Labels

Get a label

1
GET /labels/:sample_uuid/:labelset
Copied!

Response

Status: 200 OK
1
{
2
"label_type": "segmentation-bitmap",
3
"label_status": "LABELED",
4
"attributes": {
5
"format_version": "0.1",
6
"annotations": [
7
{
8
"id": 1,
9
"category_id": 0
10
}
11
],
12
"segmentation_bitmap": {
13
"url": "https://segmentsai-staging.s3.eu-west-2.amazonaws.com/assets/davy/ddf55e99-1a6f-42d2-83e9-8657de3259a1.png"
14
}
15
},
16
"created_at": "2020-04-10T20:09:31Z",
17
"created_by": "jane",
18
}
Copied!

Create or update a label

1
PUT /labels/:sample_uuid/:labelset
Copied!

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

1
{
2
"attributes": {
3
"format_version": "0.1",
4
"annotations": [
5
{
6
"id": 1,
7
"category_id": 0,
8
}
9
],
10
"segmentation_bitmap": {
11
"url": "https://example.com/label.png"
12
}
13
},
14
"label_status": "PRELABELED",
15
"score": 0.9254
16
}
Copied!

Response

Status: 201 Created
1
{
2
"attributes": {
3
"format_version": "0.1",
4
"annotations": [
5
{
6
"id": 1,
7
"category_id": 0,
8
}
9
],
10
"segmentation_bitmap": {
11
"url": "https://example.com/label.png"
12
}
13
},
14
"label_status": "PRELABELED",
15
"created_at": "2011-04-10T20:09:31Z"
16
}
Copied!

Delete a label

1
DELETE /labels/:sample_uuid/:labelset
Copied!

Releases

List releases

1
GET /datasets/:owner/:dataset/releases
Copied!

Response

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

Get a release

1
GET /datasets/:owner/:dataset/releases/:release_name
Copied!

Response

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

Create a release

1
POST /datasets/:owner/:dataset/releases
Copied!

Input

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

Example

1
{
2
"name": "v0.1",
3
"description": "My first release."
4
}
Copied!

Response

Status: 201 Created
1
{
2
"name": "v0.1",
3
"description": "My first release.",
4
"status": "PENDING",
5
"created_at": "2020-07-20T14:59:36.242218Z"
6
}
Copied!

Delete a release

1
DELETE /datasets/:owner/:dataset/releases/:release_name
Copied!

Last modified 1mo ago