> For the complete documentation index, see [llms.txt](https://taas-docs.stokr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://taas-docs.stokr.io/general-api-principles/data-handling.md).

# Standards and formats

What standards and formats we use for data and data operations?

## List endpoints

For listing endpoints (i.e., `GET /resources`), we follow the filtering, sorting, and pagination conventions of [JSON:API](https://jsonapi.org/format/1.1/). 

### Filtering

Filter results using the structure `filter[field]=value`. For example, to retrieve only equity assets:

* `GET /assets?filter[asset_type]=Equity`

For range filtering, use additional min/max parameters on any comparable field. For example, to find assets created in January 2025:

* `GET /assets?filter[created_at][min]=2025-01-01&filter[created_at][max]=2025-01-31`

### Sorting

Sort results by one or more fields using `sort=field1,-field2` (no sign means ascending order; minus sign means descending). For example, to sort assets by creation date, then by name in reverse order:

* `GET /assets?sort=created_at,-name`

### Pagination

For responses with many resources, you can use offset pagination.

Pagination parameters:

* `page[offset]` - Number of entries to skip
* `page[limit]` - Number of entries to show

The default limit is 50 resources with an offset of 0. For example, to display the 4th page (showing 50 resources while skipping the first 150):

* `GET /assets?page[offset]=150&page[limit]=50` 

Maximum limit allowed is 1000. \
Each response on the endpoints which allow pagination contain three headers to help navigate the results:

* `X-Pagination-Offset` : offset used for this result,
* `X-Pagination-Limit` : limit used for this result,
* `X-Pagination-Total` : total possible items visible via this endpoint (considering filter values).

## ISO standards

We use industry-standard formats for consistent data representation across our API.

### Country codes

[ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) alpha-2 codes (e.g. `DE` for Germany).

### Currency codes

[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) (e.g. `EUR` for Euro). Decimal places follow the same standard (e.g. `2`  for `EUR`  currency).

### Date and time

[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), depending on the specific field: 

* Date only: `2025-01-01` 
* Date and time with milliseconds in UTC: `2025-07-09T14:30:15.789Z`

## Character encoding

UTF-8 encoding with Unicode charset according to JSON standard.

## Monetary, crypto, and token values

We handle monetary amounts with precision to avoid rounding errors and ensure accurate financial calculations. All amounts include the decimal precision information needed to interpret the values correctly.

### Fiat example (1000.00 EUR)

```json
{
    "value": 100000,
    "currency": "EUR",
    "decimals": 2
}   
```

Since `EUR` uses 2 decimal places (cents), the value 100000 represents 1000.00 EUR.

### Cryptocurrency/token example (3.52 BTC)

```json
{
    "value": 352000000,
    "text_value": "3.52",
    "ticker": "BTC",
    "decimals": 8
}
```

Since Bitcoin uses 8 decimal places (satoshis), the value 352000000 represents 3.52 BTC. The `text_value` field provides a human-readable representation.