# DataSet Operation

## ListAuthStorageConfig <a href="#listauthstorageconfig" id="listauthstorageconfig"></a>

**ListAuthStorageConfig**

Acquire the list of authentication configuration

**Request path**

> **GET** /v1/auth-storage-configs

**Request parameter**

**Query**

| Name   | Type   | Required | Descriptions                                                                                    |
| ------ | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| name   | string | No       | Configuration Name                                                                              |
| limit  | int    | No       | Need to be greater than 0 and the default is 128 with a maximum of 128 for a single acquisition |
| offset | int    | No       | The default is 0                                                                                |

**Request instance**

```
curl --location --request GET '{service}/v1/auth-storage-configs?name=aws_1&limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
    "configs": [
        {
            "name": "aws_1",
            "type": "s3",
            "endpoint": "s3.cn-northwest-1.amazonaws.com.cn",
            "accesskeyId": "AKIKU7KYZCWGOTEV5GNE",
            "bucketName": "graviti-210415"
        }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}
```

## CreateDataset <a href="#createdataset" id="createdataset"></a>

**Create a dataset**

Create a TensorBay dataset with version control. The dataset name must be unique

**Request path**

> **POST** /v1/datasets

**Request parameter**

**Body**

| Name          | Type   | Required | Descriptions                                                                        |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| name          | string | Yes      | Dataset name                                                                        |
| type          | int    | No       | The default is 0, 0-normal dataset; 1-Fusion dataset                                |
| storageConfig | object | No       | Create parameters for using authenticated datasets; mutually exclusive with regions |
| ├─name        | string | Yes      | Configuration name                                                                  |
| ├─name        | path   | No       | Create storage path for datasets                                                    |

**Request instance**

```
curl --location --request POST '{service}/v1/datasets' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "my first dataset",
   "type": 0,
   "storageConfig": {
        "name": "aws_1",
        "path": "graviti"
    }
}'
```

**Output**

```
# Response status
HttpStatus 201
# Response result
{
    "id": "154e35bae8954f09969ef8c9445efd2c"
}
```

* **id**: the ID of the created dataset

## DeleteDataset <a href="#deletedataset" id="deletedataset"></a>

**Delete a dataset**

> **DELETE** /v1/datasets/{id}

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Body**

| Name   | Type   | Required | Descriptions            |
| ------ | ------ | -------- | ----------------------- |
| commit | string | No       | Commit ID or commit tag |

**Request instance**

```
curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c' \
--header 'x-token: {your_accesskey}'
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{}
```

## UpdateDataset <a href="#updatedataset" id="updatedataset"></a>

**Update dataset information**

> **PATCH** /v1/datasets/{id}

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Body**

| Name | Type   | Required | Descriptions                                                       |
| ---- | ------ | -------- | ------------------------------------------------------------------ |
| name | string | No       | dataset name, and the provided value cannot be the empty value "". |

**Request instance**

```
curl --location --request PATCH '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c' \
--header 'x-token: {your_accesskey}'\
--data-raw '{
    "name": "my dataset",
}'
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{}
```

## ListDataset <a href="#listdataset" id="listdataset"></a>

**List datasets**

Return the list of datasets owned by the user:

* Individual users acquire the list of datasets under their personal accounts
* Team users acquire the list of datasets under their enterprise accounts

**Request path**

> **GET** /v1/datasets

**Request parameter**

**Query**

| Name           | Type   | Required | Descriptions                                                                                                           |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| limit          | int    | No       | Need to be greater than 0 and the default is 128 with a maximum of 128 for a single acquisition                        |
| offset         | int    | No       | The default is 0                                                                                                       |
| name           | string | No       | Dataset name                                                                                                           |
| needFuzzyQuery | bool   | No       | If true, fuzzy query of the dataset name is supported.                                                                 |
| sortBy         | string | No       | Currently sorting is based on created\_at and updated\_at while entering other content will return InvalidParamsValue. |
| orderBy        | string | No       | The default is desc (descending order). The valid content is asc (ascending order) and desc                            |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets?offset=0&limit=10'\
--header 'x-token: {your_accesskey}'\
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
    "datasets": [
      {
        "id": "154e35bae8954f09969ef8c9445efd2c",
        "name": "my-great-data-set",
        "defaultBranch": "main",
        "type": 0,
        "updateTime": 1604977282,
        "owner": ""
      }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}
```

* **datasets**: List of datasets
  * **id**: Dataset ID
  * **name**: Dataset name
  * **defaultBranch**: default branch name
  * **type**: the default is 0, 0-normal dataset, 1-Fusion dataset

## GetDataset <a href="#getdataset" id="getdataset"></a>

**Request path**

> **GET** /v1/datasets/{id}

**Request parameter**

**PATH**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c'\
--header 'x-token: {your_accesskey}'\
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
    "name": "my-great-data-set",
    "type": 1,
    "defaultBranch": "main",
    "commitId": "00000000000000000000000000000000",
    "updateTime": 1604977282,
    "owner": ""
}
```

## CreateBranch <a href="#createbranch" id="createbranch"></a>

**Create a branch**

Create a branch

**Request path**

> **POST** /v1/datasets/{id}/branches

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Query**

| Name   | Type   | Required | Descriptions                                                                        |
| ------ | ------ | -------- | ----------------------------------------------------------------------------------- |
| name   | string | Yes      | The name of the created branch                                                      |
| commit | string | Yes      | The commit that branch is based on. It can be commit ID, commit tag, or branch name |

**Request instance**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/branches' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json'\
--data-raw '{
  "name": main2,
  "commit": "fde63f357daf46088639e9f57fd81cad"
}'
```

**Output**

```
# Response status
HttpStatus 201
# Response result
{}
```

## DeleteBranch <a href="#deletebranch" id="deletebranch"></a>

**Delete branch**

Delete branch

**Request path**

> **DELETE** /v1/datasets/{id}/branches

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Query**

| Name | Type   | Required | Descriptions |
| ---- | ------ | -------- | ------------ |
| name | string | Yes      | Branch name  |

**Request instance**

```
curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/branches' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json'\
--data-raw '{
  "name": main2
}'
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{}
```

## ListBranch <a href="#listbranch" id="listbranch"></a>

**Acquire a branch list**

Acquire a list of dataset branches

**Request path**

> **GET** /v1/datasets/{id}/branches

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Query**

| Name   | Type | Required | Descriptions                                                                                    |
| ------ | ---- | -------- | ----------------------------------------------------------------------------------------------- |
| limit  | int  | No       | Need to be greater than 0 and the default is 128 with a maximum of 128 for a single acquisition |
| offset | int  | No       | The default is 0                                                                                |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/branches?limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
    "branches": [
        {
            "name": "main",
            "commitId": "fde63f357daf46088639e9f57fd81cad",
            "parentCommitId": "f68b1375454f459b8a486b8d1f4d9ddb",
            "title": "first commit",
            "committer": {
                "name": "graviti",
                "date": 1616579313
            }
        }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}
```

## CreateDraft <a href="#createdraft" id="createdraft"></a>

**Create a dataset draft**

Create a TensorBay dataset draft. Only one draft can be created on a branch

**Request path**

> **POST** /v1/datasets/{id}/drafts

**Request parameter**

**Path**

| Name | Required | Descriptions |
| ---- | -------- | ------------ |
| id   | Yes      | Dataset ID   |

**Body**

| Name       | Type   | Required | Descriptions                                     |
| ---------- | ------ | -------- | ------------------------------------------------ |
| title      | string | No       | Draft name                                       |
| branchName | string | No       | Branch name. The default branch is named as main |

**Request instance**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/drafts' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "my first draft",
  "branchName": "main"
}'
```

**Output**

```
# Response status
HttpStatus 201
# Response result
{
    "draftNumber": 1
}
```

* **draftNumber**: draft number

## ListDraft <a href="#listdraft" id="listdraft"></a>

**Acquire a list of dataset drafts**

Acquire a list of dataset drafts

**Request path**

> **GET** /v1/datasets/{id}/drafts

**Request parameter**

**Path**

| Name | Required | Descriptions |
| ---- | -------- | ------------ |
| id   | Yes      | Dataset ID   |

**Query**

| Name   | Type | Required | Descriptions                                                                                    |
| ------ | ---- | -------- | ----------------------------------------------------------------------------------------------- |
| limit  | int  | No       | Need to be greater than 0 and the default is 128 with a maximum of 128 for a single acquisition |
| offset | int  | No       | The default is 0                                                                                |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/drafts?limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
  "drafts": [
    {
      "draftNumber": "1",
      "branchName": "main",
      "title": "my first draft"
    }
  ],
  "offset": 0,
  "recordSize": 1,
  "totalCount": 10
}
```

## CommitDataset <a href="#commitdataset" id="commitdataset"></a>

**Commit a dataset**

Update a dataset with a pending status to a committed status. Once a dataset is published, it cannot be modified.

**Request path**

> **POST** /v1/datasets/{id}

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Body**

| Name        | Type   | Required | Descriptions                                                            |
| ----------- | ------ | -------- | ----------------------------------------------------------------------- |
| draftNumber | int    | Yes      | Draft number                                                            |
| title       | string | yes      | The number of characters of the submitted title should be less than 255 |
| tag         | string | No       | Dataset version tag. The number of characters should range from 2 to 80 |

**Request instance**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c'\
--header 'x-token: {your_accesskey}'\
--header 'Content-Type: application/json' \
--data-raw '{
  "draftNumber": "1",
  "title": "checkout a new version dataset",
  "tag": "v1.0"
}'
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
  "commitId": "fde63f357daf46088639e9f57fd81cad"
}
```

## ListCommit <a href="#listcommit" id="listcommit"></a>

**list commits**

Acquire a list of dataset commits

**Request path**

> **GET** /v1/datasets/{id}/commits

**Request parameter** **Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Query**

| Name   | Type   | Required | Descriptions                                                             |
| ------ | ------ | -------- | ------------------------------------------------------------------------ |
| commit | string | No       | Commit ID, commit tag, or branch name. The default is the default branch |
| limit  | int    | No       | The default is set to 128. The maximum value for a single time is 128    |
| offset | int    | No       | The default is 0                                                         |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/commits?commit=main&limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
  "commits": [
    {
      "parentCommitId": "0d213a06a85d46fa8662946bdb1afe7e",
      "commitId": "fde63f357daf46088639e9f57fd81cad",
      "title": "checkout a new version dataset",
      "committer": {
        "date": 1617268600,
        "name": "graviti"
      }
    }
  ],
  "offset": 0,
  "recordSize": 1,
  "totalCount": 10
}
```

## CreateTag <a href="#createtag" id="createtag"></a>

**Create a tag**

Create a tag

**Request path**

> **POST** /v1/datasets/{id}/tags

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Body**

| Name   | Type   | Required | Descriptions                                                 |
| ------ | ------ | -------- | ------------------------------------------------------------ |
| commit | string | Yes      | Commit ID, commit tag, or branch name                        |
| name   | string | Yes      | Tag name. The number of characters should range from 2 to 80 |

**Request instance**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/tags' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "commit": "fde63f357daf46088639e9f57fd81cad",
  "name": "v1"
}'
```

**Output**

```
# Response status
HttpStatus 201
# Response result
{}
```

## DeleteTag <a href="#deletetag" id="deletetag"></a>

**Delete a tag**

Delete a tag

**Request path**

> **DELETE** /v1/datasets/{id}/tags

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Body**

| Name | Type   | Required | Descriptions |
| ---- | ------ | -------- | ------------ |
| name | string | Yes      | tag name     |

**Request instance**

```
curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/tags' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "v1"
}'
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{}
```

## ListTag <a href="#listtag" id="listtag"></a>

**List tags**

Acquire a list of dataset tags

**Request path**

> **GET** /v1/datasets/{id}/tags

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Query**

| Name   | Type   | Required | Descriptions                                                          |
| ------ | ------ | -------- | --------------------------------------------------------------------- |
| name   | string | 否        | tag name                                                              |
| limit  | int    | No       | The default is set to 128. The maximum value for a single time is 128 |
| offset | int    | No       | The default is 0                                                      |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/tags?name=v1&limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
    "tags": [
        {
            "name": "v1",
            "commitId": "fde63f357daf46088639e9f57fd81cad",
            "parentCommitId": "f68b1375454f459b8a486b8d1f4d9ddb",
            "title": "first commit",
            "committer": {
                "name": "graviti",
                "date": 1617268600
            }
        }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}
```

## updateNote <a href="#updatenote" id="updatenote"></a>

**Update a dataset note**

Update a dataset note

**Request path**

> **PATCH** /v1/datasets/{id}/notes

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Body**

| Name                | Type      | Required | Descriptions                                    |
| ------------------- | --------- | -------- | ----------------------------------------------- |
| draftNumber         | int       | Yes      | draft number                                    |
| binPointCloudFields | string\[] | No       | Dimension name of the point cloud in bin format |
| isContinuous        | bool      | No       | Is it continuous                                |

**Request instance**

```
curl --location --request PATCH '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/notes' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "draftNumber": 1,
  "fileFormat": {
    "draftNumber": 1,
    "binPointCloudFields": [
       "X",
       "Y",
       "Z",
       "Intensity"
    ],
    "isContinuous": true
}'
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{}
```

## GetNote <a href="#getnote" id="getnote"></a>

**Get note**

Get the note of a dataset

**Request path**

> **GET** /v1/datasets/{id}/notes

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Query**

| Name        | Type   | Required | Descriptions                                                                                        |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| draftNumber | int    | No       | Draft number. Only one of draft and commit should exist, but they should not exist at the same time |
| commit      | string | No       | Commit ID, commit tag, or branch name                                                               |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/notes?draftNumber=1' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
    "isContinuous": true，
    "binPointCloudFields": [
        "X",
        "Y",
        "Z",
        "Intensity"
    ]
}
```


---

# 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.graviti.com/dev-doc/tools/api-center/dataset-operation.md?ask=<question>
```

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.