API - Documentation

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.
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
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!
​
Reference - Previous
Categories and task attributes
Last modified 5mo ago
Datasets

List datasets

Response

Get a dataset

Response

Create a dataset

Input

Example

Response

Update a dataset

Delete a dataset

Add a collaborator to a dataset

Input

Example

Response

Samples

List samples

Response

Get a sample

Response

Create a sample

Input

Example

Response

Update a sample

Delete a sample

Labels

Get a label

Response

Create or update a label

Input

Example

Response

Delete a label

Releases

List releases

Response

Get a release

Response

Create a release

Input

Example

Response

Delete a release

​
