Mantis Bug Tracker REST API

REST API calls have to be authenticated by creating an API token for the user doing the calls, and then passing the API token in the 'Authorization' header. However, for anonymous access, the API key and header are not needed.

The token is passed using the standard RFC 6750 bearer scheme (Authorization: Bearer <token>); the scheme name is matched case-insensitively. For backwards compatibility, the bare form (Authorization: <token>) is also still accepted.

There has been significant improvements and feature additions for REST API in each of the recent releases. Hence, it is highly recommended to use latest release when leveraging the REST APIs.

REST API is enabled by default since MantisBT 2.8.0 release.

Getting started

All paths in this document are relative to the MantisBT installation. For example, an installation at https://mantis.example.com serves this API at https://mantis.example.com/api/rest. Use the non-trailing-slash form shown in this document. Requests and responses use JSON unless an endpoint explicitly documents a different format.

Create an API token in MantisBT, then send the token value directly in the Authorization header. Do not prefix the token with Bearer:

Authorization: <api-token>
Content-Type: application/json

Browser requests authenticated with a MantisBT session cookie are also supported. When anonymous access is enabled, read operations may be available without either credential; permissions still apply in every case.

Common request conventions

Object references generally accept an id or name, allowing clients to use stable numeric identifiers while still supporting readable payloads. List endpoints that expose page and page_size use one-based page numbers. The select query parameter accepts a comma-separated list of fields, which is useful for reducing response size when only a subset is required.

File uploads are JSON payloads: each entry in files has a filename in name and base64-encoded data in content.

Conditional issue updates

Issue reads return an ETag. Send it in If-Match on issue updates or deletes to prevent overwriting a newer version; a stale value produces 412 Precondition Failed and returns the current ETag. Send the same value in If-None-Match on a read to receive 304 Not Modified when the issue has not changed.

Errors and response headers

Successful responses identify the effective user and authentication method in X-Mantis-Username and X-Mantis-LoginMethod; X-Mantis-Version reports the running MantisBT version. A 204 response intentionally has no response body. Errors use the HTTP status code and may include JSON fields such as message, code, and localized.

Impersonation

Users with the access level defined by $g_impersonate_user_threshold (default: ADMINISTRATOR) can execute REST API calls on behalf of another user by adding the X-Mantis-Username request header containing the target username. Impersonation requires API token authentication; it is not available with cookie or anonymous access.

Constraints:

  • The caller must authenticate with an API token.
  • The caller must have at least the $g_impersonate_user_threshold access level.
  • A user cannot impersonate themselves.
  • A user cannot impersonate a user with a higher access level than their own.
  • The target user must be a valid, enabled user.

Response Headers

Every API response includes the following informational headers:

  • X-Mantis-Username – The username under which the request was executed (the impersonated user's name when impersonation is active).
  • X-Mantis-LoginMethod – The authentication method used: api-token, cookie, or anonymous.