Skip to main content
Version: Hosted
Version: 1

Mender API Reference

Welcome to the Mender API reference documentation.

This comprehensive API specification covers all the features of the different Mender backend services and is suitable for code generation applications, integration with third-party systems, and building custom tooling.

Introduction​

REST API​

The Mender API is a RESTful API designed to allow you to get, create, update, and delete objects using the HTTP verbs GET, POST, PUT, PATCH, and DELETE. The APIs make use of CORS (cross-origin requests) which also uses the OPTIONS request method.

API Organization​

The Mender APIs are organized into three main categories, accessible through the sidebar navigation:

Device APIs​

Device APIs are designed for device-originating requests. These endpoints are used by Mender clients running on devices to:

  • Check for software updates
  • Report deployment status
  • Send inventory data
  • Receive and report configuration

Management APIs​

Management APIs are intended for use by the Mender UI, CLI tools, and other management applications. These APIs allow you to:

  • Manage devices, users, and deployments
  • Upload and manage artifacts and releases
  • Configure device settings
  • Monitor device health and alerts
  • Access audit logs
  • Manage tenants and subscriptions

Internal APIs​

Internal APIs are used by Mender's backend services to communicate with each other. They can also be used to integrate third-party systems with the backend when installing Mender on-premise.

note

The API gateway does not expose Internal API endpoints on hosted Mender; they are not available for direct consumption by external clients.

Getting Started​

Use the sidebar to navigate through the available endpoints. Each endpoint includes:

  • Detailed descriptions of parameters and request bodies
  • Example requests in multiple formats
  • Response schemas and status codes
  • Authentication requirements

You can also download the complete OpenAPI specification using the "OpenAPI Spec" button above.

Personal Access Tokens​

The JWT tokens returned by login endpoints expire after one week. For programmatic access from CI/CD pipelines or scheduled jobs, we recommend using Personal Access Tokens. These are long-lived JWT tokens that act as API keys, allowing you to access the Management APIs without frequent re-authentication.

Learn more about Personal Access Tokens

Common HTTP Response Codes​

In addition to endpoint-specific responses, the following HTTP response codes are common across the API:

HTTP CodeDescription
401 UnauthorizedThe request is missing the Authorization header or its content is not valid
403 ForbiddenThe request is forbidden for the current user or device by Role-based Access Control (RBAC) settings
429 Too Many RequestsThe client is flooding the server with too many requests and is required to slow down
500 Internal Server ErrorThe backend failed to process the request because of an unexpected server-side error

API Versioning and Compatibility​

The Mender APIs are continuously reviewed and improved. The following changes are considered backwards-compatible:

  • Adding new endpoints
  • Extending existing endpoints with additional attributes
  • Supporting additional query parameters for existing endpoints

If API compatibility needs to be broken, the version number in the URI will be increased (e.g., from /api/management/v1/deployments to /api/management/v2/deployments). Both versions will be supported for a transition period to allow for graceful migration.

Authentication​

Endpoints that require authentication expect an Authorization header containing a valid JWT token in the following format:

Authorization: Bearer {access-token}

Authentication Schemes​

API token issued by User Authentication service.

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

JWT