# Data API

## When to use it

You would use the Data API when you have an array of customer domain data and want to do any of the following things:

* allow the webapp user to choose a value for some field from a predefined set, not adding another value to the set;
* validate the user input against a predefined set of values both on frontend and backend;
* populate some more fields based on the user’s choice in another field;
* allow to choose values for different fields, thus filtering and narrowing down the choices for the following fields belonging to the same set of data;
* limit the availability of the whole set to a certain account;
* limit the availability of certain fields to frontend.

## How to use it

A typical usage flow:

* The frontend app requests a list of items for a dropdown to display on the field with the dataset rule from the Data API, specifying the dataset fields;
* The Data API responds with a list of item IDs and values for the chosen dataset fields;
* User selects a value;
* The frontend app requests a single dataset item by its ID;
* The API responds with the full set of public fields for the item;
* The frontend app submits a dataset item ID in the payload for the field instead of a set of fields (e.g. company data) to the quote or policy API, e.g. `"some_field”: ”dai_some_dataset_item_id________”`.

## How to retrieve the data

Note

All of the retrieval samples below show unauthenticated requests for publicly available datasets.

When you need to access a dataset locked to an account, add an `Authentication: Bearer YOUR_TOKEN` header to the request.

### Get a dataset information record

## Get a dataset information record

<mark style="color:blue;">`GET`</mark> `https://api.kaskocloud.com/datasets/{datasetId}`

#### Path Parameters

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| datasetId<mark style="color:red;">\*</mark> | String | Dataset ID  |

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

```json
{
    "id": "dat_abcxyz______________________",
    "name": "Some dataset name",
    "languages": ["en", "de"]
}
```

{% endtab %}
{% endtabs %}

### List items from a set

## List items from a set.

<mark style="color:blue;">`GET`</mark> `https://api.kaskocloud.com/datasets/{datasetId}/dataset_items`

#### Path Parameters

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| datasetId<mark style="color:red;">\*</mark> | String | Dataset ID  |

#### Query Parameters

| Name                                       | Type    | Description                                      |
| ------------------------------------------ | ------- | ------------------------------------------------ |
| language<mark style="color:red;">\*</mark> | String  | Language                                         |
| fields<mark style="color:red;">\*</mark>   | JSON    | Fields to output in the `value` property         |
| limit<mark style="color:red;">\*</mark>    | Integer | Number of items per page, 1 to 100, default = 20 |
| starting\_after                            | String  | Item ID to start the page after                  |
| ending\_before                             | String  | Item ID to end the page before                   |
| query                                      | JSON    | Search query                                     |
| sort                                       | JSON    | Sorting order                                    |

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

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    [
        {    
            "id": "dai_abcxyz",
            "value": {
                "name": "Kasko",
                "code": "Z1",
            }
        }
    ]
}
</code></pre>

{% endtab %}
{% endtabs %}

The `query` parameter format is `[{"field": "FIELD", "search": "VALUE", "operator": "OPTIONAL_OPERATOR"}]`.

The `search` field of the `query` parameter supports `%` wildcards; the accepted operators are `>`, `>=`, `<`, `<=`, and `IN`. The type of the value is array for the `IN` operator and string for everything else.

Sample `search` value:

```
[
  {"field": "name", "search": "Kas%"},
  {"field": "price", "operator": ">", "search": "10"},
  {"field": "category", "operator": "IN", "search": ["a", "b"]}
]
```

The `sort` parameter format is `[{"field": "FIELD", "dir": "asc|desc"}]`.

**Example Request**

```
curl 'https://api.kasko.io/datasets/DATASET_ID/dataset_items' \
    -d language=de \
    -d fields=["name","code"]
```

The `Link` header holds the links for the next and previous page queries.

### List distinct values of a field in a dataset

## List items from a set.

<mark style="color:blue;">`GET`</mark> `https://api.kaskocloud.com/datasets/{datasetId}/items_distinct_values`

#### Path Parameters

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| datasetId<mark style="color:red;">\*</mark> | String | Dataset ID  |

#### Query Parameters

| Name                                       | Type    | Description                                      |
| ------------------------------------------ | ------- | ------------------------------------------------ |
| language<mark style="color:red;">\*</mark> | String  | Language                                         |
| fields<mark style="color:red;">\*</mark>   | JSON    | Fields to output in the `value` property         |
| limit<mark style="color:red;">\*</mark>    | Integer | Number of items per page, 1 to 100, default = 20 |
| starting\_after                            | String  | Item ID to start the page after                  |
| ending\_before                             | String  | Item ID to end the page before                   |
| query                                      | JSON    | Search query                                     |
| sort                                       | JSON    | Sorting order                                    |

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

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    [
        {    
            "id": "dai_abcxyz",
            "value": {
                "name": "Kasko",
                "code": "Z1",
            }
        }
    ]
}
</code></pre>

{% endtab %}
{% endtabs %}

### Get one item

## Get dataset item

<mark style="color:blue;">`GET`</mark> `https://api.kaskocloud.com/dataset_items/{itemId}`

#### Query Parameters

| Name                                       | Type   | Description |
| ------------------------------------------ | ------ | ----------- |
| language<mark style="color:red;">\*</mark> | String | Language    |

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

```json
{
    "id": "dai_abcxyz",
    "data": {
        "field_name": "field_value"
    }
}
```

{% endtab %}
{% endtabs %}

### Sending data to backend

Instead of the literal values in the dataset item you send the item ID.

**Example Request For a Quote:**

```
GET https://api.kaskocloud.com/quote?data=
{
  ...
  "company": "dai_123_some_item_id_____________",
  ...
}
```

The backend service transparently converts this input to the full item available to use in pricing, policy, etc.


---

# 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.kasko.io/kasko-api-documentation/rest-api/data-api.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.