Getting Started

Introduction

The Miru API is a RESTful service that allows you to interact with your workspace via HTTP requests. You can create an API with set permissions as to not expose any sensitive data.

Creating an API Key

To create an API key, navigate to Settings > API in the admin dashboard. Bare in mind that an API key can only access data inside the workspace, which means that you need to create an API key for each workspace you want to access.

API versioning

The Miru API is versioned and will only keep the previous version from it's latest release. This means that if the latest version was v3, v1 would be removed but v2 would still be available up until the next major API release.

The current latest version is v1, which is the only version available at the moment.

Handling Errors

Miru's API uses standard HTTP status codes to provide context about the success of a failure. It also provides a JSON response with a error boolean that indicates whether the request was successful or not. It's recommended to prioritize the HTTP status code over the error boolean, as it provides more context about the error.

An example

Here's an example of how to use the API to fetch information about a monitor:

curl -X GET 'https://status.example.com/api/v1/monitor/<monitor_id>' -H "x-api-key: <api_key>"

If the API key is valid, hasn't expired and has the monitor.read permission, this will return a JSON response with the monitor's information.

{
	"error": false,
	"monitor": {
		"id": "MAWVBk3M134tB5zX",
		"workspaceId": "oxf6K1uBV8VoIXVr",
		"name": "Website",
		"type": "http",
		"url": "nordstud.io",
		"interval": 5,
		"createdAt": "2025-05-11T19:42:06.009Z",
		"updatedAt": "2025-05-11T19:42:06.009Z"
	}
}

If the API key is invalid, expired or doesn't have the monitor.read permission, this will return a JSON response some an error message describing the issue.

{
	"error": true,
	"message": "Invalid API key"
}

Available areas

Currently, there are four areas that you can interact with via the API: