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

{% hint style="info" %} Note that this will only return datasets which are public, and datasets which are private but where the logged in user is a collaborator. {% endhint %}

Response

{% code title="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        
    }
]

{% endcode %}

Get a dataset

GET /datasets/:owner/:dataset

Response

{% code title="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.",
        },
    ]
}

{% endcode %}

Create a dataset

POST /user/datasets

Input

Name	Type	Description
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

{% code title="Status: 201 Created" %}

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

{% endcode %}

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

{% code title="Status: 201 Created" %}

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

{% endcode %}

Samples

List samples

GET /datasets/:owner/:dataset/samples

Response

{% code title="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"
  }
]

{% endcode %}

Get a sample

GET /samples/:sample_uuid

Response

{% code title="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"
}

{% endcode %}

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

{% code title="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"
}

{% endcode %}

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

{% code title="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",
}

{% endcode %}

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

{% code title="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"
}

{% endcode %}

Delete a label

DELETE /labels/:sample_uuid/:labelset

Releases

List releases

GET /datasets/:owner/:dataset/releases

Response

{% code title="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"
  }
]

{% endcode %}

Get a release

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

Response

{% code title="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"
}

{% endcode %}

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

{% code title="Status: 201 Created" %}

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

{% endcode %}

Delete a release

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

Files

api.md

Latest commit

History

api.md

File metadata and controls

API

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