# API The API is available at \*\*; To authenticate, add an API key in the header of each request: ```bash curl -H "Authorization: APIKey YOUR_API_KEY" ``` An API key can be created on your [user account page](https://segments.ai/account). ## Datasets ### List datasets ```bash GET /users/:owner/datasets ``` To get all datasets of the currently logged in users, you can use this shortcut: ```bash 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" %} ```bash [ { "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 ```bash GET /datasets/:owner/:dataset ``` #### Response {% code title="Status: 200 OK" %} ```bash { "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 ```bash POST /user/datasets ``` #### Input
NameTypeDescription
NameTypeDescription
namestringRequired. The name of the dataset.
categorystringRequired. Category of the data, e.g. "other"
task_typestring

Required. 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_attributesdictRequired. The task attributes. See Configuring the label editor.
descriptionstringThe description of the dataset.
publicboolean

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.
readmestringThe readme of the dataset, displayed on the overview tab.
enable_skip_labelingbooleanEnable the skip button in the labeling workflow. Defaults to True.
enable_skip_reviewingbooleanEnable the skip button in the reviewing workflow. Defaults to False.
enable_ratingsbooleanEnable star-ratings for labeled images. Defaults to False.
#### Example ```bash { "name": "cats", "description": "A dataset of cat images." } ``` #### Response {% code title="Status: 201 Created" %} ```bash { "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 ```bash PATCH /datasets/:owner/:dataset ``` Same fields as previous. ### Delete a dataset ```bash DELETE /datasets/:owner/:dataset ``` ### Add a collaborator to a dataset ```bash 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 ```bash { "user": "jane", "role": "reviewer" } ``` #### Response {% code title="Status: 201 Created" %} ```bash { "user": "jane", "role": "reviewer" } ``` {% endcode %} ## Samples ### List samples ```bash GET /datasets/:owner/:dataset/samples ``` #### Response {% code title="Status: 200 OK" %} ```bash [ { "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 ```bash GET /samples/:sample_uuid ``` #### Response {% code title="Status: 200 OK" %} ```bash { "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 ```bash 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 ```bash { "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" %} ```bash { "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 ```bash PATCH /samples/:sample_uuid ``` Same fields as previous. ### Delete a sample ```bash DELETE /samples/:sample_uuid ``` ## Labels ### Get a label ```bash GET /labels/:sample_uuid/:labelset ``` #### Response {% code title="Status: 200 OK" %} ```bash { "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 ```bash PUT /labels/:sample_uuid/:labelset ``` #### Input | Name | Type | Description | | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `attributes` | `object` | Label data. Format depends on the label type, see [label formats](/reference/label-types.md). | | `label_status` | `string` |

Status of the label.

Can be one of: LABELED, REVIEWED, REJECTED, PRELABELED, SKIPPED

| | `score` | `float` | Prediction score. | #### Example ```bash { "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" %} ```bash { "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 ```bash DELETE /labels/:sample_uuid/:labelset ``` ## Releases ### List releases ```bash GET /datasets/:owner/:dataset/releases ``` #### Response {% code title="Status: 200 OK" %} ```bash [ { "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 ```bash GET /datasets/:owner/:dataset/releases/:release_name ``` #### Response {% code title="Status: 200 OK" %} ```bash { "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 ```bash 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 ```bash { "name": "v0.1", "description": "My first release." } ``` #### Response {% code title="Status: 201 Created" %} ```bash { "name": "v0.1", "description": "My first release.", "status": "PENDING", "created_at": "2020-07-20T14:59:36.242218Z" } ``` {% endcode %} ### Delete a release ```bash DELETE /datasets/:owner/:dataset/releases/:release_name ``` ## --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.segments.ai/reference/api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.