The mStudio v2 API uses
https://api.mittwald.de/v2/ as base URL for all API endpoints.
You can find the full API specification in the OpenAPI 3.0 format here:
Obtaining an API token
To authenticate to the API, you will need an API Token. You can obtain one either via the mittwald mStudio Web UI or via the API itself (if you already have another API token).
In the UI, go to your user profile and choose the API tokens menu item.
Alternatively, via the API, use the
/v2/signup/token/apiendpoint. This requires you to already have an existing API token:
POST /v2/signup/token/api HTTP/1.1
Authorization: Bearer <EXISTING_API_TOKEN>
"description": "My API token",
"roles": ["api_read", "api_write"]
The response will contain a JSON document with a
tokenkey. This is your API token.
Make sure to store your API token in a secure place. It is the only way to authenticate to the API. A lost token cannot be recovered.
Once you have obtained an API token, there are two ways to authenticate to the API:
X-Access-TokenHTTP header. The value of the header is just the API token itself.
GET /v2/user HTTP/1.1
AuthorizationHTTP header, providing the API token as a
GET /v2/user HTTP/1.1
Authorization: Bearer <API_TOKEN>
Usage of the API is rate-limited to prevent abuse. You can inspect the rate limiting for your current user by observing the headers included in each response:
X-RateLimit-Limit: The maximum number of requests you are allowed to make per period.
X-RateLimit-Remaining: The number of requests remaining in the current period.
X-RateLimit-Reset: The remaining time (in seconds) until the current rate limit period ends and a new one begins.
Some special routes may be exempt from rate limiting. These routes will respond with a
X-RateLimit-Exempt header set to
The read models of our event sourced architecture are eventually consistent. If you want to learn about this, have a read of the blog post about event sourcing. As a consequence, changes being made by a POST, PUT, PATCH or DELETE request may take a moment until all read models are updated. This may cause a (GET) request executed immediately after the mutating request to run into an error, typically with an HTTP status code like
403. To handle this eventual consistency, you can use a combination of the response header
etag and the request header
To prevent the issue, you might use the event id returned in the
etag header of the mutating request.
This event id might be used as the value for the
if-event-reached header of the subsequent (GET) request. If this header is set, the processing services will wait until the event is handled. After the event is handled, the service will execute and answer the request.
Please note, that such a request can fail with
412 Precondition Failed if the event is not reached within 10 seconds.