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_name/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": "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_name/:dataset_name

Response

Status: 200 OK
{
"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-07-20T14:59:36.242218Z",
"collaborators_count": 0,
"samples_count": 94,
"tasks": [
{
"name": "segmentation",
"task_type": "segmentation-bitmap",
"attributes": {
"format_version": "0.1",
"categories": [
{
"name": "cat",
"id": 0
},
{
"name": "dog",
"id": 1
}
]
},
"created_at": "2020-07-20T14:59:42.675157Z"
}
]
}

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.

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

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

Response

Status: 201 Created
{
"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-07-20T14:59:36.242218Z",
"collaborators_count": 0,
"samples_count": 94
}

Delete a dataset

DELETE /datasets/:owner_name/:dataset_name

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"}
}
"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"}
}
"created_at": "2020-04-10T20:09:31Z"
"created_by": "jane"
}

Create a sample

POST /datasets/:owner/:dataset/samples

Input

Name

Type

Description

name

string

Required. The name of the sample.

attributes

object

Sample data.

Example

{
"name": "flowers.png",
"attributes": {
"image": {
"url": "https://example.com/image.png"
}
}
}

Response

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

Delete a sample

DELETE /samples/:sample_uuid

Labels

Get a label

GET /labels/:sample_uuid/:task_name

Response

Status: 200 OK
{
"label_type": "segmentation-bitmap",
"label_status": "LABELED",
"attributes": {
"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/:task_name

Input

Name

Type

Description

attributes

object

Label data.

label_status

string

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"
}

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/:task_name