# Datasets

Our Datasets endpoint can be used to programmatically import data either as a new dataset, or appended to an existing one. 

## Get Dataset(s)

<mark style="color:blue;">`GET`</mark> `https://api.akkio.com/v1/datasets`

Get all datasets in your organization, or optionally get a specific dataset

#### Query Parameters

| Name                                       | Type   | Description                                                                  |
| ------------------------------------------ | ------ | ---------------------------------------------------------------------------- |
| id                                         | string | (Optional): If dataset ID is included, only the specific dataset is returned |
| api\_key<mark style="color:red;">\*</mark> | string | Your api key, accessible from <https://app.akkio.com/team-settings>          |

{% tabs %}
{% tab title="200 Example response with and without specific IDs" %}
{% tabs %}
{% tab title="Without id " %}

```javascript
{
    "status": "success",
    "datasets": [
        {
            "id": "7pmPB4MXU390Bs0Axxnd",
            "name": "Telco-Customer-Churn.csv"
        },
        {
            "id": "83BxRLqOADMfgEPTZI7v",
            "name": "Historic Conversions.csv"
        },
        {
            "id": "9eEQ4Rp92y9Z6Cws4Sot",
            "name": "titanic-sheet-titanic"
        }
    ]
}
```

{% endtab %}

{% tab title="With ID " %}

```
{
    "status": "success",
    "name": "titanic-sheet-titanic",
    "rows": 887,
    "fields": [
        {
            "type": "category",
            "name": "Survived"
        },
        {
            "type": "category",
            "name": "Pclass"
        },
        {
            "name": "Name",
            "type": "string"
        },
        {
            "name": "Sex",
            "type": "category"
        },
    ]
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 " %}

```javascript
{
    "status": "missing or invalid API key"
}
```

{% endtab %}
{% endtabs %}

```bash
# Example cURL to list all datasets

 curl 'https://api.akkio.com/v1/datasets?api_key=api_key_string' 
```

```bash
#Example cURL to list detailed information about one dataset

curl 'https://api.akkio.com/v1/datasets?api_key=api_key_string&id=id_string' 
```

## Create Dataset

<mark style="color:green;">`POST`</mark> `https://api.akkio.com/v1/datasets`

Creates a dataset with a given name

#### Request Body

| Name                                       | Type   | Description                                                         |
| ------------------------------------------ | ------ | ------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark>     | string | The name of the dataset to be created                               |
| api\_key<mark style="color:red;">\*</mark> | string | Your API key, accessible from <https://app.akkio.com/team-settings> |

{% tabs %}
{% tab title="200 " %}

```
{
    "status": "success",
    "dataset_id": "YOUR_DATASET_ID",
    "dataset_name": "YOUR_DATASET_NAME"
}
```

{% endtab %}
{% endtabs %}

```bash
# Example cURL to create a new empty dataset

curl --request POST 'https://api.akkio.com/v1/datasets?name=name_string&api_key=api_key_string'
```

## Add Rows To Dataset

<mark style="color:green;">`POST`</mark> `https://api.akkio.com/v1/datasets`

#### Request Body

| Name                                        | Type   | Description                                                                        |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------- |
| rows                                        | array  | List of rows in form \[{'field name 1': 'value 1', 'field name 2': 0}, {...}, ...] |
| id                                          | string | The ID of the dataset to add rows to                                               |
| api\_key <mark style="color:red;">\*</mark> | string | Your API key, accessible from <https://app.akkio.com/team-settings>                |

{% tabs %}
{% tab title="200 " %}

```
{
    "status": "success"
}
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
NOTE! The first time you add data to your dataset, it will define the schema for that dataset
{% endhint %}

```bash
# Example cURL 1 - passing in via form body, entirely command-line (no character limit)
curl -g --request POST --location 'https://api.akkio.com/v1/datasets?id=id_string&api_key=api_key_string' \
-H "Content-Type: application/json" \
-d '{"rows":"[{\"field name 1\": \"value 1\", \"field name 2\": \"value 2\"}]"}'
```

```bash
# Example cURL 2 - passing in via form body & file named data.json (no character limit)
curl -g --request POST --location 'https://api.akkio.com/v1/datasets?id=id_string&api_key=api_key_string' \
-H "Content-Type: application/json" \
-d @data.json
```

{% hint style="warning" %}
When passing data via the form body, make sure the JSON is of the form:

`{`\
&#x20;  `"rows": [`\
&#x20;    `{<row1>},`\
&#x20;    `{<row2>}`\
&#x20;  `]`\
&#x20;`}`
{% endhint %}

## Delete Dataset

<mark style="color:red;">`DELETE`</mark> `https://api.akkio.com/v1/datasets`

Deletes a given dataset from a given ID

#### Request Body

| Name                                       | Type   | Description                                                         |
| ------------------------------------------ | ------ | ------------------------------------------------------------------- |
| api\_key<mark style="color:red;">\*</mark> | string | Your API key, accessible from <https://app.akkio.com/team-settings> |
| id                                         | string | The ID of the dataset                                               |

{% tabs %}
{% tab title="200 " %}

```
{
    "status": "success"
}
```

{% endtab %}
{% endtabs %}

```bash
# Example cURL

curl --request DELETE 'https://api.akkio.com/v1/datasets?id=id_string&api_key=api_key_string'
```