# 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'
```


---

# 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.akkio.com/akkio-docs/endpoints-and-schemas/endpoints/datasets.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.