> 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

## 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://taas-docs.stokr.io/general-api-principles/data-handling.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.