> 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/endpoints-and-requests.md).

# Endpoints and requests

## Resource structure

Our API is based on REST principles. We use the following HTTP verbs:

* **POST -** Create new resources or trigger processes in your tokenization workflow.
* **PATCH** - Update existing resources, modify collections, or deactivate resources.
* **GET -** Retrieve information about specific resources or search through lists with filtering.

In specific, but rare, cases we use **PUT** verb. For example in permissions change endpoint in order to simplify building UIs that use this endpoint.

Each resource gets a unique `id` in UUIDv4 format. You can also provide your own `external_reference` for any resource to maintain references between our platform and your internal systems.

All endpoint paths are kept to the minimum necessary set of nested resources.

## Breaking changes

When we update our API, changes are classified as either **breaking** or **non-breaking**.

**Breaking changes** could disrupt your integration:

* Request/response parameter type changes, removals, or renames
* Stricter validation rules on request parameters
* Reduced possible values for request parameters
* Endpoint deprecations

We announce breaking changes in advance with clear transition timelines and migration guidance.

**Non-breaking changes** don't affect existing integrations: 

* New optional parameters
* Additional data in responses
* Relaxed validation rules
* Expanded request parameter value options

Non-breaking changes may be released with short notice since they shouldn't impact your systems.

## Versioning

API endpoints include the version number in the URL path (like `https://url.com/v1/resource`). The current version of the API is `v1`.

Major version changes involve complete endpoint versioning and may include significant logic changes. New versions are announced well in advance with migration support.

## Request tracing

We provide two tracking mechanisms for troubleshooting:

* **Outbound Request ID**: We assign a unique identifier (UUIDv4 format) to every request and include it in the response header (`X-Request-Id`  header) for both successful and error responses. This gives you a reference for support requests.
* **Inbound Request ID**: You can optionally include your own tracking ID in request header (`X-Client-Request-Id` header). This helps trace requests when network issues prevent you from receiving our response. The header is also passed into for both successful and error response headers.

Logging both IDs speeds up issue resolution when problems occur. When contacting support, please provide one or both request IDs to help us investigate issues quickly.

## Idempotency

For `POST` and `PATCH` operations, you can include an optional idempotency key (UUIDv4 format) to prevent unintended duplicate actions from network timeouts, accidental retries, or job queue issues.

If we receive a previously used idempotency key, we return the original result instead of processing the action again. Keys are stored for 30 days and scoped by resource type.

This prevents duplicate transactions during critical operations like token issuance or investor onboarding.


---

# 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/endpoints-and-requests.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.