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 must be passed using the standard RFC 6750 bearer scheme
(Authorization: Bearer <token>); the scheme name is matched case-insensitively.
The REST API is kept current with the latest MantisHub code.
Getting started
All paths in this document are relative to your MantisHub instance. For example, an
instance at https://instance-name.mantishub.io serves this API at
https://instance-name.mantishub.io/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 MantisHub, then send it in the Authorization header with the
Bearer prefix:
Browser requests authenticated with a MantisHub 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
MantisHub 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.
This aggregate document includes the core MantisBT API and the published plugin APIs: ApiX, Dantis, Lavatar, Pages, RecurringTasks.
Status selector: all. Internal operations are excluded from documentation and API clients.
Creates a token for the authenticated user. Store the returned token securely: it is the
credential sent in the Authorization header for subsequent API calls.
Parameters
Name
In
Type
Description
X-Mantis-Username
header
string
Username to impersonate for this request. Requires an authorized API token.
Request body
namestring
Responses
201
Resource created successfullyX-Mantis-UsernameX-Mantis-LoginMethodX-Mantis-Version
"string"
400
Bad Request
401
Authentication is required or the supplied API token is invalid.WWW-Authenticate
403
The authenticated user is not authorized for this operation, impersonation, or API access level.
404
Entity not found
503
MantisHub is temporarily unavailable and cannot process API requests.
Creates a token for another user. This requires permission to impersonate that user and
cannot target a user with a higher access level than the caller.
Parameters
Name
In
Type
Description
user_idrequired
path
integer
The user ID
e.g. 5
X-Mantis-Username
header
string
Username to impersonate for this request. Requires an authorized API token.
Request body
namestring
Responses
201
Resource created successfullyX-Mantis-UsernameX-Mantis-LoginMethodX-Mantis-Version
"string"
400
Bad Request
401
Authentication is required or the supplied API token is invalid.WWW-Authenticate
403
The authenticated user is not authorized for this operation, impersonation, or API access level.
404
Entity not found
503
MantisHub is temporarily unavailable and cannot process API requests.
Returns issues visible to the effective user. Use project_id to scope the search and
filter_id for a built-in or saved filter. Results are paginated; omit select to use
the default issue fields. The response includes an ETag; send it in If-None-Match
to receive 304 Not Modified when the result has not changed.
Parameters
Name
In
Type
Description
X-Mantis-Username
header
string
Username to impersonate for this request. Requires an authorized API token.
If-None-Match
header
string
ETag returned by a prior issue read. A matching value returns 304 without a response body.
When creating an issue, most of the fields other than summary, description and category are typically optional.
It is also worth noting that when passing references to enumerations like priority or object references like handler,
it is sufficient to pass the id or name.
Parameters
Name
In
Type
Description
X-Mantis-Username
header
string
Username to impersonate for this request. Requires an authorized API token.
Request body
required
idinteger
summarystring
descriptionstring
steps_to_reproducestring
additional_informationstring
projectobject
namestring
categoryobject
namestring
handlerobject
namestring
emailstring
reporterobject
namestring
emailstring
statusobject
idnumber
namestring
labelstring
resolutionobject
idnumber
namestring
labelstring
projectionobject
idnumber
namestring
labelstring
etaobject
idnumber
namestring
labelstring
view_stateobject
idnumber
namestring
labelstring
priorityobject
idnumber
namestring
labelstring
severityobject
idnumber
namestring
labelstring
reproducibilityobject
idnumber
namestring
labelstring
versionobject
namestring
fixed_in_versionobject
namestring
target_versionobject
namestring
stickybooleansticky issues show at the top of the View Issues page.
due_datestring · date
date_submittedstring · date-time
date_updatedstring · date-time
osstring
os_buildstring
buildstring
platformstring
profile_idinteger
profileobject
created_atstring · date-time
updated_atstring · date-time
attachmentsobject[]
idinteger
reporterobject
namestring
emailstring
created_atstring · date-time
filenamestring
sizeinteger
content_typestring
contentstring · byteBase64-encoded file content.
relationshipsobject[]
tagsobject[]
historyobject[]
notesobject[]
idinteger
textstring
reporterobject
namestring
emailstring
view_stateobject
idnumber
namestring
labelstring
typestring
attrstring
created_atstring · date-time
updated_atstring · date-time
attachmentsobject[]
idinteger
reporterobject
namestring
emailstring
created_atstring · date-time
filenamestring
sizeinteger
content_typestring
contentstring · byteBase64-encoded file content.
time_trackingobject
durationstring
filesobject[]
namestring
contentstring
monitorsobject[]
namestring
emailstring
filesobject[]
namestring
contentstring
custom_fieldsobject[]
fieldobject
idnumber
namestring
valuestring
Responses
201
Resource created successfullyX-Mantis-UsernameX-Mantis-LoginMethodX-Mantis-Version
"string"
202
Request accepted for moderationX-Mantis-UsernameX-Mantis-LoginMethodX-Mantis-Version
400
Bad Request
401
Authentication is required or the supplied API token is invalid.WWW-Authenticate
403
The authenticated user is not authorized for this operation, impersonation, or API access level.
404
Entity not found
503
MantisHub is temporarily unavailable and cannot process API requests.
Applies the supplied fields to an existing issue. For optimistic concurrency, first read
the issue and send its ETag in If-Match. A mismatch returns 412 Precondition Failed.
Parameters
Name
In
Type
Description
idrequired
path
integer
The issue ID
e.g. 123
X-Mantis-Username
header
string
Username to impersonate for this request. Requires an authorized API token.
If-Match
header
string
ETag returned by a prior issue read. The operation fails with 412 if it no longer matches.
Returns the ApiX discovery document for the current instance. Use it to identify the available API surface and instance metadata before making feature-specific calls.
Lists issues visible to the authenticated user using the same filter and sort semantics as MantisBT issue lists. The request can select a project, apply issue-filter criteria, choose sort fields and order, and paginate the result. Set describe=1 to include the filter's MQL representation and compact=1 to request the compact response form.
Request body
projectstringProject reference; omit or use the all-projects reference to search across projects.
filterstringJSON issue-filter criteria.
sort_bystringIssue field used for sorting.
sort_orderstringSort direction accepted by the issue-filter implementation.
pageintegerOne-based result page; defaults to `1`.
page_sizeintegerMaximum number of issues returned per page; the server applies its configured limits.
formatstringExport format; issue export defaults to `csv`.
columnsstring[]Ordered columns to include in an export.
Exports the visible issue list using the supplied project, filter, sort, and column selections. The format body field defaults to csv; the export response is generated from the same issue-list data used by the list operation.
Request body
projectstringProject reference; omit or use the all-projects reference to search across projects.
filterstringJSON issue-filter criteria.
sort_bystringIssue field used for sorting.
sort_orderstringSort direction accepted by the issue-filter implementation.
pageintegerOne-based result page; defaults to `1`.
page_sizeintegerMaximum number of issues returned per page; the server applies its configured limits.
formatstringExport format; issue export defaults to `csv`.
columnsstring[]Ordered columns to include in an export.
Creates an issue through MantisBT's issue-add workflow. The body must identify the destination project and can include the standard issue fields, custom_fields, base64-encoded files, due_date, and clone_info. The command checks project access, custom-field permissions, attachment data, clone options, and due-date permissions before creating the issue.
Request body
idintegerExisting issue ID. Used by update requests when supplied in the body.
projectstringDestination or current project reference, normally an object containing a numeric `id`.
summarystringShort issue title.
descriptionstringMain issue description.
handlerstringUser assigned to handle the issue.
reporterstringUser reported as the issue author.
statusstringWorkflow status for the issue.
resolutionstringResolution applied during an update or status change.
due_datestringDue date accepted by MantisBT date parsing; setting it requires the configured due-date permission.
target_versionstringVersion targeted by the issue.
fixed_in_versionstringVersion in which the issue was fixed.
custom_fieldsstring[]Custom-field values; ApiX maps the client representation to the MantisBT REST representation.
filesstring[]Base64-encoded file attachments converted to temporary upload files before issue creation.
clone_infoobjectClone options forwarded to the issue-add workflow.
notestringOptional note data recorded with an issue update.
Assigns an issue to the user identified by the body handler field. An optional note is added as part of the assignment and due_date may be supplied when the caller has permission to change due dates. select controls the fields returned in the updated issue view.
Parameters
Name
In
Type
Description
issue_idrequired
path
integer
ApiX issue_id path parameter.
Request body
handlerstringUser assigned to the issue.
notestringOptional note recorded with the action.
due_datestringDue date to apply when the caller has permission.
Moves an issue to the destination project in the body project reference. An optional note records the move with the issue. The destination project must exist and be writable by the caller.
Parameters
Name
In
Type
Description
issue_idrequired
path
integer
ApiX issue_id path parameter.
Request body
idintegerExisting issue ID. Used by update requests when supplied in the body.
projectstringDestination or current project reference, normally an object containing a numeric `id`.
summarystringShort issue title.
descriptionstringMain issue description.
handlerstringUser assigned to handle the issue.
reporterstringUser reported as the issue author.
statusstringWorkflow status for the issue.
resolutionstringResolution applied during an update or status change.
due_datestringDue date accepted by MantisBT date parsing; setting it requires the configured due-date permission.
target_versionstringVersion targeted by the issue.
fixed_in_versionstringVersion in which the issue was fixed.
custom_fieldsstring[]Custom-field values; ApiX maps the client representation to the MantisBT REST representation.
filesstring[]Base64-encoded file attachments converted to temporary upload files before issue creation.
clone_infoobjectClone options forwarded to the issue-add workflow.
notestringOptional note data recorded with an issue update.
Adds a note to an issue. text is the note content; optional type, reporter, view_state, time_tracking, and base64-encoded files control note metadata and attachments. Mentions in the text are processed for notifications.
Parameters
Name
In
Type
Description
issue_idrequired
path
integer
ApiX issue_id path parameter.
Request body
textstringNote content. Mentions in the text are processed for notifications.
typestringNote type; defaults to `note`.
reporterstringUser to record as the note reporter, subject to permission checks.
view_statestringNote visibility state.
privatebooleanWhether an updated note is private.
time_trackingstringTime-tracking value associated with the note.
filesstring[]Base64-encoded attachments associated with the note.
Updates an existing issue note. The body may replace text, change private, and update time_tracking; the caller must be allowed to edit the selected note.
Parameters
Name
In
Type
Description
issue_idrequired
path
integer
ApiX issue_id path parameter.
note_idrequired
path
integer
ApiX note_id path parameter.
Request body
textstringNote content. Mentions in the text are processed for notifications.
typestringNote type; defaults to `note`.
reporterstringUser to record as the note reporter, subject to permission checks.
view_statestringNote visibility state.
privatebooleanWhether an updated note is private.
time_trackingstringTime-tracking value associated with the note.
filesstring[]Base64-encoded attachments associated with the note.
This operation is implemented by the ApiX issue_view_page command. A read-only wiki relationship group (type.id: 1001) carries a page object whose issue_id is the issue an existing page belongs to (0 when none), or the issue to send as issue_id when creating a page that does not exist yet. A bare issue id is reserved for that issue's page, so such a reference is returned only when the issue is in the same project and readable.
Creates a relationship between the path issue and another issue using the relationship payload accepted by MantisBT. The caller must be able to view both issues and add relationships to the source issue.
Changes an issue's status and applies the related workflow fields. The body can contain status, resolution, fixed_in_version, target_version, duplicate_id, handler, custom_fields, due_date, and an optional note; each field is checked against the configured workflow and permissions.
Parameters
Name
In
Type
Description
issue_idrequired
path
integer
ApiX issue_id path parameter.
Request body
idintegerExisting issue ID. Used by update requests when supplied in the body.
projectstringDestination or current project reference, normally an object containing a numeric `id`.
summarystringShort issue title.
descriptionstringMain issue description.
handlerstringUser assigned to handle the issue.
reporterstringUser reported as the issue author.
statusstringWorkflow status for the issue.
resolutionstringResolution applied during an update or status change.
due_datestringDue date accepted by MantisBT date parsing; setting it requires the configured due-date permission.
target_versionstringVersion targeted by the issue.
fixed_in_versionstringVersion in which the issue was fixed.
custom_fieldsstring[]Custom-field values; ApiX maps the client representation to the MantisBT REST representation.
filesstring[]Base64-encoded file attachments converted to temporary upload files before issue creation.
clone_infoobjectClone options forwarded to the issue-add workflow.
notestringOptional note data recorded with an issue update.
Updates an existing issue through MantisBT's issue-update workflow. The path identifies the issue; the body may also contain the issue id, a replacement project, standard issue fields, custom fields, and an optional note.
Parameters
Name
In
Type
Description
issue_idrequired
path
integer
ApiX issue_id path parameter.
Request body
idintegerExisting issue ID. Used by update requests when supplied in the body.
projectstringDestination or current project reference, normally an object containing a numeric `id`.
summarystringShort issue title.
descriptionstringMain issue description.
handlerstringUser assigned to handle the issue.
reporterstringUser reported as the issue author.
statusstringWorkflow status for the issue.
resolutionstringResolution applied during an update or status change.
due_datestringDue date accepted by MantisBT date parsing; setting it requires the configured due-date permission.
target_versionstringVersion targeted by the issue.
fixed_in_versionstringVersion in which the issue was fixed.
custom_fieldsstring[]Custom-field values; ApiX maps the client representation to the MantisBT REST representation.
filesstring[]Base64-encoded file attachments converted to temporary upload files before issue creation.
clone_infoobjectClone options forwarded to the issue-add workflow.
notestringOptional note data recorded with an issue update.
Lists custom-field definitions visible to the authenticated user. sort_by and sort_order select the list ordering; field visibility and project linkage are resolved by ApiX.
Creates a custom-field definition. The custom_field body object contains the field definition; ApiX validates its name and type, then optionally links it to the projects listed by the payload.
Request body
custom_fieldobjectrequiredCustom-field definition. ApiX sanitizes and validates the definition before persistence.
namestringField name; ApiX enforces the MantisBT name length limit.
typestringMantisBT custom-field type.
possible_valuesstringAllowed values for enumerated field types.
default_valuestringDefault value for the field.
display_reportbooleanShow the field on issue creation.
display_updatebooleanShow the field on issue updates.
projectsstring[]Project IDs to link to the custom field; omitted on create means no additional links.
Reads or updates the authenticated user's issue-list columns for a project. The body identifies the project and may provide a type (default view) and an ordered columns list.
Request body
projectstringProject reference, normally an object containing `id`.
typestringColumn configuration type; defaults to `view`.
columnsstring[]Ordered column identifiers to save.
Updates ApiX/MantisHub configuration values using the settings payload. Configuration names and values are validated by the management command, and write access is required.
Creates a project through MantisBT's project-add workflow. The body contains the project definition accepted by the core command, including its name, description, status, view state, and inheritance settings where supported.
Request body
idintegerExisting project ID for update payloads.
namestringProject name.
descriptionstringProject description.
statusstringProject status.
view_statestringProject visibility state.
inherit_globalbooleanWhether project settings inherit global values where supported.
Updates the specified project using the core project-update workflow. Only fields accepted by that workflow are applied, and project-management permissions are required.
Parameters
Name
In
Type
Description
project_idrequired
path
integer
ApiX project_id path parameter.
Request body
idintegerExisting project ID for update payloads.
namestringProject name.
descriptionstringProject description.
statusstringProject status.
view_statestringProject visibility state.
inherit_globalbooleanWhether project settings inherit global values where supported.
Copies selected project relations from source_project_id into the destination project. project_relation selects the relation set (such as categories, custom fields, or versions); exclude_inherited controls inherited records when supported.
Parameters
Name
In
Type
Description
project_idrequired
path
integer
ApiX project_id path parameter.
Request body
source_project_idintegerrequiredExisting project from which relations are copied.
project_relationstringrequiredRelation set to copy.categoriescustom_fieldsversionsusers
exclude_inheritedbooleanFor category copying, exclude inherited categories; defaults to `false`.
Lists saved filters available in the project. The optional limit query parameter defaults to 100. Results are restricted according to the caller's filter visibility and project access.
Creates a saved project filter. type must be saved, name must be non-empty and unique, criteria must be an array of filter criteria, and shared controls whether the filter is shared when the caller has the required permission.
Parameters
Name
In
Type
Description
project_idrequired
path
integer
ApiX project_id path parameter.
Request body
typestringrequiredFilter kind. ApiX currently accepts only `saved`.saved
namestringrequiredNon-empty, project-unique filter name; MantisBT limits it to 64 characters.
sharedbooleanShare the filter with other permitted users; defaults to `false`.
criteriastring[]requiredJSON filter criteria converted to MantisBT's stored filter format.
Returns one project filter. The filter_id path value may be a numeric filter ID or a filter name, subject to the caller's project visibility and filter permissions.
Updates a saved project filter. The body can change its name, criteria, shared state, and type; the implementation accepts only the saved filter type and revalidates name uniqueness and sharing permissions.
Parameters
Name
In
Type
Description
project_idrequired
path
integer
ApiX project_id path parameter.
filter_idrequired
path
integer
ApiX filter_id path parameter.
Request body
typestringrequiredFilter kind. ApiX currently accepts only `saved`.saved
namestringrequiredNon-empty, project-unique filter name; MantisBT limits it to 64 characters.
sharedbooleanShare the filter with other permitted users; defaults to `false`.
criteriastring[]requiredJSON filter criteria converted to MantisBT's stored filter format.
Assigns all issues in issues to the body handler and can add the supplied note to each issue. The project path selects the permission and issue context.
Parameters
Name
In
Type
Description
project_idrequired
path
integer
ApiX project_id path parameter.
Request body
issuesstring[]requiredIssue references to process.
fieldsobjectWorkflow fields applied to each issue.
Closes multiple issues in one project-scoped operation. issues identifies the issues to process and fields supplies the workflow fields applied while closing them.
Parameters
Name
In
Type
Description
project_idrequired
path
integer
ApiX project_id path parameter.
Request body
issuesstring[]requiredIssue references to process.
fieldsobjectWorkflow fields applied to each issue.
Returns the current readable wiki page for a project by name. The optional revision selector can request a specific revision; page and note visibility are enforced for the authenticated user.
Parameters
Name
In
Type
Description
project_idrequired
path
integer
ApiX project_id path parameter.
page_namerequired
path
string
Wiki page name within the project.
revision_id
query
integer
Optional revision ID; omit to return the current page revision.
Creates a project wiki page through the Pages plugin. The optional issue_id query parameter associates the new page with an existing readable issue in the same project; that association is made at creation time.
Parameters
Name
In
Type
Description
project_idrequired
path
integer
ApiX project_id path parameter.
issue_id
query
integer
Issue whose wiki page is being created. Must exist in this project and be readable by the caller.
Updates the named project wiki page through the Pages plugin, including its content and page-note data supplied by the request. The page must be writable by the authenticated user.
Builds a project time-tracking report for the requested date range. start_date and end_date define the period, and cost_per_hour overrides the configured billing rate. This endpoint reports only the selected project; include_subprojects is supported by the export endpoint, not this report endpoint.
Parameters
Name
In
Type
Description
project_idrequired
path
integer
ApiX project_id path parameter.
Request body
start_datestringStart of the reporting period.
end_datestringEnd of the reporting period.
cost_per_hournumberBilling rate override; otherwise the configured rate is used.
Exports project time-tracking/billing data in the path-selected export_type. Query values include from, to, cost, and include_subprojects; the project and date values are validated before export.
Resolves batches of issue, note, and mention references and returns the related user/avatar information used by clients. Send the reference collections in the JSON body; avatar_size controls the requested avatar dimensions.
Request body
issuesstring[]Issue references to resolve.
notesstring[]Note references to resolve.
mentionsstring[]Mention references to resolve.
avatar_sizeintegerRequested avatar size in pixels.
Searches MantisBT entities for the authenticated user. text is the search term; types limits the entity types returned, project scopes the search, issue_id provides issue context, and limit caps the result count. Set auto_complete or include_current_user when the client needs those specialized results.
Request body
textstringSearch text or autocomplete prefix.
auto_completebooleanEnables autocomplete behavior; defaults to `false`.
limitintegerMaximum number of matches; defaults to `10`.
include_current_userbooleanInclude the authenticated user in user matches; defaults to `false`.
projectstringOptional project reference used to scope the search.
issue_idintegerOptional issue context for searches that resolve related values.
typesstring[]Entity types to search; omitted types use the command's default set.
Searches snippets visible to the authenticated user. text supplies the search term, limit caps the result count, and project_id scopes the search (all projects by default).
Parameters
Name
In
Type
Description
text
query
string
Text used to search snippet names and content.
limit
query
integer
Maximum number of snippets to return; defaults to 10.
project_id
query
integer
Project to search; omitted to search across all projects visible to the caller.
Changes the authenticated user's password. Send both password_current and password; the command validates the current credential before applying the new one.
Request body
password_currentstring · passwordrequiredCurrent password of the authenticated user.
passwordstring · passwordrequiredNew password; it must satisfy the instance password rules.
Updates the authenticated user's self-service settings. The body is a map of supported setting names to values; unsupported or malformed settings are rejected.
Request body
configsobject[]requiredNon-empty list of permitted self-service settings.
optionstringrequiredAllowed setting name. The server determines the permitted option set.
valuestringrequiredNew value for the selected setting.
Creates a user through MantisBT's user-create workflow. The body supplies the account definition accepted by core, including username, email, access level, enabled state, and optional preferences.
Request body
usernamestringUnique account username.
emailstring · emailUser email address.
realnamestringDisplay name.
passwordstring · passwordAccount password when creating or changing a user.
access_levelintegerGlobal access level.
enabledbooleanWhether the account is enabled.
protectedbooleanWhether the account is protected from ordinary administration.
languagestringPreferred language.
timezonestringPreferred timezone.
client_preferredbooleanWhether the user prefers the client-specific interface.
avatarstringAvatar data accepted by the configured avatar integration.
notify_userbooleanWhether to notify the user about the update.
password_currentstring · passwordCurrent password required for applicable password changes.
Returns a user by numeric ID or username. Use select to limit the returned user fields; access to disabled users and sensitive fields follows MantisBT permissions.
Updates a user through MantisBT's user-update workflow. The body supports account fields such as language, timezone, client_preferred, avatar, and notification settings; password changes require the current password where applicable.
Parameters
Name
In
Type
Description
user_idrequired
path
string
ApiX user_id path parameter.
Request body
usernamestringUnique account username.
emailstring · emailUser email address.
realnamestringDisplay name.
passwordstring · passwordAccount password when creating or changing a user.
access_levelintegerGlobal access level.
enabledbooleanWhether the account is enabled.
protectedbooleanWhether the account is protected from ordinary administration.
languagestringPreferred language.
timezonestringPreferred timezone.
client_preferredbooleanWhether the user prefers the client-specific interface.
avatarstringAvatar data accepted by the configured avatar integration.
notify_userbooleanWhether to notify the user about the update.
password_currentstring · passwordCurrent password required for applicable password changes.
Starts an impersonated session for the target user. This administrative operation is permission-gated and changes the authenticated user context; use it only when the caller is authorized to impersonate that account.
Resets the target user's account state using the core reset workflow. This administrative operation does not accept a replacement password in the path.
Returns the named dashboard in edit form plus permissions and the same project-specific editor configuration as the create endpoint. Missing home is represented by the generated default dashboard.
Parameters
Name
In
Type
Description
project_idrequired
path
integer · int32
Numeric MantisBT project ID.
namerequired
path
string
Dashboard name within the project. The reserved default name is `home`.
Responses
200
Configuration and dashboard used by the edit page.
dashboardobject
idstringrequiredPersisted dashboard ID; generated default dashboards may use an empty or synthetic ID.
namestringrequired
titlestringrequired
projectobjectrequired
idintegerrequired
namestringrequired
ownerobjectrequired
idintegerrequired
namestring
real_namestring
emailstring
avatarstring · uri
definitionobject[]required
layoutstringrequiredSection layout; widgets must support it.1-col2-col4-col
widgetsstring[]required
enabledbooleanrequired
favoritebooleanrequiredWhether the current user favorited it; generated `home` dashboards are true.
Returns a named dashboard, its resolved widget data, and permissions. If name is home and no saved dashboard exists, the project default dashboard is generated in memory.
Parameters
Name
In
Type
Description
project_idrequired
path
integer · int32
Numeric MantisBT project ID.
namerequired
path
string
Dashboard name within the project. The reserved default name is `home`.
Responses
200
Dashboard and reporting-page permissions.
dashboardobjectrequired
idstringrequiredPersisted dashboard ID; generated default dashboards may use an empty or synthetic ID.
namestringrequired
titlestringrequired
projectobjectrequired
idintegerrequired
namestringrequired
ownerobjectrequired
idintegerrequired
namestring
real_namestring
emailstring
avatarstring · uri
definitionobject[]required
layoutstringrequiredSection layout; widgets must support it.1-col2-col4-col
widgetsstring[]required
enabledbooleanrequired
favoritebooleanrequiredWhether the current user favorited it; generated `home` dashboards are true.
Creates a dashboard in a visible project. The name must be unique in the project, title is limited to 64 characters, and every definition section must contain at least one widget supported by the selected layout.
Request body
required
namestringrequiredUnique project-local dashboard name; `home` is reserved.
titlestringDisplay title. Required for non-default dashboards.
project_idinteger · int32requiredProject that owns the dashboard.
definitionobject[]requiredNon-empty ordered sections; each section must contain at least one widget.
layoutstringrequiredSection layout; widgets must support it.1-col2-col4-col
widgetsstring[]required
Responses
201
Dashboard created.
idstringrequired
namestringrequired
{
"id": "string",
"name": "string"
}
400
Invalid project, dashboard ID/name, widget, filter, or dashboard definition.
Updates the supplied fields of a dashboard owned by the caller. The default home dashboard may also be updated by users with project management permission. The response is the edit-page representation.
Parameters
Name
In
Type
Description
idrequired
path
string
32-character dashboard identifier returned by the create endpoint.
Request body
required
namestringNew project-local name; it cannot be the reserved `home` name.
titlestringNew display title; the default dashboard always uses the project name.
definitionobject[]
layoutstringrequiredSection layout; widgets must support it.1-col2-col4-col
widgetsstring[]required
Responses
200
Dashboard updated.
dashboardobjectrequired
idstringrequiredPersisted dashboard ID; generated default dashboards may use an empty or synthetic ID.
namestringrequired
titlestringrequired
projectobjectrequired
idintegerrequired
namestringrequired
ownerobjectrequired
idintegerrequired
namestring
real_namestring
emailstring
avatarstring · uri
definitionobject[]required
layoutstringrequiredSection layout; widgets must support it.1-col2-col4-col
widgetsstring[]required
enabledbooleanrequired
favoritebooleanrequiredWhether the current user favorited it; generated `home` dashboards are true.
Updates a named dashboard. For the reserved home name, Dantis creates the project default dashboard when it does not yet exist; other missing dashboards return not found.
Parameters
Name
In
Type
Description
project_idrequired
path
integer · int32
Numeric MantisBT project ID.
namerequired
path
string
Dashboard name within the project. The reserved default name is `home`.
Request body
required
namestringNew project-local name; it cannot be the reserved `home` name.
titlestringNew display title; the default dashboard always uses the project name.
definitionobject[]
layoutstringrequiredSection layout; widgets must support it.1-col2-col4-col
widgetsstring[]required
Responses
200
Dashboard updated or the missing default dashboard created.
dashboardobjectrequired
idstringrequiredPersisted dashboard ID; generated default dashboards may use an empty or synthetic ID.
namestringrequired
titlestringrequired
projectobjectrequired
idintegerrequired
namestringrequired
ownerobjectrequired
idintegerrequired
namestring
real_namestring
emailstring
avatarstring · uri
definitionobject[]required
layoutstringrequiredSection layout; widgets must support it.1-col2-col4-col
widgetsstring[]required
enabledbooleanrequired
favoritebooleanrequiredWhether the current user favorited it; generated `home` dashboards are true.
Validates a widget configuration for a project and returns its serialized configuration. On view, edit, or create pages the response also contains widget data when that widget supports it; widget data failures are returned in the widget's error property.
Request body
required
project_idinteger · int32required
pagestringControls whether resolved widget data is attached. `list` is used internally for dashboard lists.vieweditcreate
widgetstringrequired
Responses
200
Serialized widget and, for non-list pages, its resolved data.
"string"
400
Invalid project, dashboard ID/name, widget, filter, or dashboard definition.
Adds an avatar for the specified user. If that user already has an avatar, the existing file is deleted before the new image is stored. The authenticated user may update their own avatar. Updating another user's avatar requires the configured MantisBT manage-user access level. Protected users cannot have an avatar added or replaced.
Request body
required
user_idinteger · int32requiredNumeric MantisBT user ID to associate with the avatar.
avatar_imagestringrequiredBase64 data URI containing the image bytes, for example `data:image/png;base64,<encoded-bytes>`. The decoded image must be JPEG (`image/jpeg`) or PNG (`image/png`) and no larger than 1 MiB (1,048,576 bytes). This endpoint accepts a JSON request body; it does not accept multipart/form-data.
Responses
201
Avatar upload completed. The command returns JSON null.
"string"
400
The user ID or image data is missing or invalid, the image format is unsupported, or the image exceeds 1 MiB.
messagestringrequiredTechnical error message from the failed operation.
codeintegerrequiredMantisBT error code associated with the failure.
localizedstringrequiredLocalized MantisBT description for the error code.
{
"message": "User id is missing or invalid.",
"code": 11,
"localized": "A necessary field was empty. Please recheck your inputs."
}
401
Authentication is required or the supplied API token is invalid.
403
The caller cannot modify the target user, or the target account is protected.
messagestringrequiredTechnical error message from the failed operation.
codeintegerrequiredMantisBT error code associated with the failure.
localizedstringrequiredLocalized MantisBT description for the error code.
{
"message": "User id is missing or invalid.",
"code": 11,
"localized": "A necessary field was empty. Please recheck your inputs."
}
404
The target user does not exist.
messagestringrequiredTechnical error message from the failed operation.
codeintegerrequiredMantisBT error code associated with the failure.
localizedstringrequiredLocalized MantisBT description for the error code.
{
"message": "User id is missing or invalid.",
"code": 11,
"localized": "A necessary field was empty. Please recheck your inputs."
}
500
Avatar storage failed unexpectedly.
messagestringrequiredException message describing the failed operation.
{
"message": "User does not have an avatar attached."
}
Removes the stored avatar for the specified user. The authenticated user may delete their own avatar. Deleting another user's avatar requires the configured MantisBT manage-user access level. Protected users cannot have an avatar deleted, and a user without an avatar produces an internal error from the command implementation.
Parameters
Name
In
Type
Description
user_idrequired
path
integer · int32
Numeric MantisBT user ID whose avatar is being changed.
e.g. 42
Responses
204
Avatar deleted successfully. No response body is returned.
400
The user ID is missing or invalid.
messagestringrequiredTechnical error message from the failed operation.
codeintegerrequiredMantisBT error code associated with the failure.
localizedstringrequiredLocalized MantisBT description for the error code.
{
"message": "User id is missing or invalid.",
"code": 11,
"localized": "A necessary field was empty. Please recheck your inputs."
}
401
Authentication is required or the supplied API token is invalid.
403
The caller cannot modify the target user, or the target account is protected.
messagestringrequiredTechnical error message from the failed operation.
codeintegerrequiredMantisBT error code associated with the failure.
localizedstringrequiredLocalized MantisBT description for the error code.
{
"message": "User id is missing or invalid.",
"code": 11,
"localized": "A necessary field was empty. Please recheck your inputs."
}
404
The target user does not exist.
messagestringrequiredTechnical error message from the failed operation.
codeintegerrequiredMantisBT error code associated with the failure.
localizedstringrequiredLocalized MantisBT description for the error code.
{
"message": "User id is missing or invalid.",
"code": 11,
"localized": "A necessary field was empty. Please recheck your inputs."
}
500
The target user does not have an attached avatar, or avatar deletion failed.
messagestringrequiredException message describing the failed operation.
{
"message": "User does not have an avatar attached."
}
Replaces the note text after checking the caller's page-note modification permission. The response contains the updated note with Pages attachment URLs and semantic-link text.
Parameters
Name
In
Type
Description
note_idrequired
path
integer
Numeric ID of the page note.
Request body
required
textstringrequiredReplacement markdown note text.
Responses
200
Note updated.
noteobjectrequired
idintegerrequiredNote ID.
containerstringrequiredNotes container owned by Pages.page-notes
ref_idintegerrequiredPage ID to which the note belongs.
project_idintegerrequiredOwning project ID.
reporterobjectrequiredUser representation returned for page authors and note reporters.
idintegerNumeric user ID.
namestringUsername.
real_namestringDisplay name when configured.
emailstring · emailUser email address when visible.
enabledbooleanWhether the account is enabled.
avatarstringAvatar data when avatars are enabled.
textstringrequiredMarkdown note text after Pages semantic-link expansion.
typestringNote type returned by the Notes plugin.
view_statestringNote visibility state when supplied by Notes.
time_trackingstringTime-tracking value when supplied by Notes.
Returns notes attached to the page in the authenticated user's configured note order. Page view permission controls visibility; each note includes the Pages-generated attachment download URL and markdown semantic-link text.
Parameters
Name
In
Type
Description
page_idrequired
path
integer
Numeric ID of the page.
Responses
200
Page notes.
notesobject[]requiredNotes attached to the requested page.
idintegerrequiredNote ID.
containerstringrequiredNotes container owned by Pages.page-notes
ref_idintegerrequiredPage ID to which the note belongs.
project_idintegerrequiredOwning project ID.
reporterobjectrequiredUser representation returned for page authors and note reporters.
idintegerNumeric user ID.
namestringUsername.
real_namestringDisplay name when configured.
emailstring · emailUser email address when visible.
enabledbooleanWhether the account is enabled.
avatarstringAvatar data when avatars are enabled.
textstringrequiredMarkdown note text after Pages semantic-link expansion.
typestringNote type returned by the Notes plugin.
view_statestringNote visibility state when supplied by Notes.
time_trackingstringTime-tracking value when supplied by Notes.
Creates a markdown note attached to the page. text defaults to an empty string when omitted. Base64 attachments are handed to the Notes plugin, then decorated with a Pages download URL; the command also sends mention notifications and returns the page's current collaborators.
Parameters
Name
In
Type
Description
page_idrequired
path
integer
Numeric ID of the page.
Request body
required
textstringMarkdown note text; defaults to an empty string.
filesstring[]Optional base64 attachments passed to the Notes plugin.
Responses
201
Note created.
noteobjectrequired
idintegerrequiredNote ID.
containerstringrequiredNotes container owned by Pages.page-notes
ref_idintegerrequiredPage ID to which the note belongs.
project_idintegerrequiredOwning project ID.
reporterobjectrequiredUser representation returned for page authors and note reporters.
idintegerNumeric user ID.
namestringUsername.
real_namestringDisplay name when configured.
emailstring · emailUser email address when visible.
enabledbooleanWhether the account is enabled.
avatarstringAvatar data when avatars are enabled.
textstringrequiredMarkdown note text after Pages semantic-link expansion.
typestringNote type returned by the Notes plugin.
view_statestringNote visibility state when supplied by Notes.
time_trackingstringTime-tracking value when supplied by Notes.
Creates a page in the supplied project. name, title, and non-empty markdown content are required. If issue_id is supplied, the page is associated with that issue and its name must be the issue ID (a padded numeric name is normalized). files may contain base64 attachments; duplicate filenames are ignored. The response includes the created page, its attachment metadata, and its revision history.
Request body
required
namestringPage name; omitted only when creating an issue-associated page.
titlestringrequiredPage title.
contentstringrequiredMarkdown content; HTML is not required for images or references.
projectobjectrequiredMantisBT project reference accepted by page commands.
idintegerNumeric project ID.
namestringProject name.
issue_idintegerOptional issue to associate with the page.
messagestringRevision message recorded for the creation.
filesobject[]Optional base64 attachments. Duplicate filenames are ignored.
Updates an existing page selected by id, or selects it by project and name when id is omitted. Supplied name, title, and content fields replace their current values; omitted fields are retained. A rename updates page references and cannot rename an issue-associated page. New base64 attachments can be supplied in files; duplicate filenames are ignored. The response contains the updated page.
Request body
required
idintegerExisting page ID; use this or project plus name.
projectobjectMantisBT project reference accepted by page commands.
idintegerNumeric project ID.
namestringProject name.
namestringExisting page name when selecting by project and name, or replacement name for an ordinary page.
titlestringReplacement page title.
contentstringReplacement markdown content.
messagestringRevision message.
filesobject[]Optional new base64 attachments. Duplicate filenames are ignored.
Returns the visible page, its markdown content, page attachment metadata, and page links. Link entries identify whether each referenced page currently exists.
Parameters
Name
In
Type
Description
page_idrequired
path
integer
Numeric ID of the page.
Responses
200
Page details.
pageobjectrequired
idintegerrequiredNumeric page ID.
namestringrequiredURL-safe page name.
titlestringrequiredHuman-readable page title.
projectobjectrequiredMantisBT project reference accepted by page commands.
idintegerNumeric project ID.
namestringProject name.
issue_idintegerAssociated issue ID; null for an ordinary project page.
created_byobjectrequiredUser representation returned for page authors and note reporters.
idintegerNumeric user ID.
namestringUsername.
real_namestringDisplay name when configured.
emailstring · emailUser email address when visible.
Moves an ordinary page to a different project. Page attachments and page-note attachments are relocated, note rows are reassigned, and markdown references are rewritten for the source and target projects. Issue-associated pages cannot be moved independently; they follow the issue move workflow. The successful response has an empty JSON object.
Parameters
Name
In
Type
Description
page_idrequired
path
integer
Numeric ID of the page.
target_project_idrequired
path
integer
Numeric ID of the project receiving the page.
Responses
200
Page moved; the command returns an empty JSON object.
[]
400
The JSON body or one of its fields is invalid.
401
Authentication is required or the API token is invalid.
403
The authenticated user does not have the required project or note permission.
404
The page, project, revision, note, or attachment was not found.
cURL
curl -X POST \
-H "Authorization: Bearer $MANTIS_TOKEN" \
https://yourmantishubname.mantishub.io/api/rest/plugins/Pages/1/move/1
Creates a recurring task for the supplied project. By default the task is personal and belongs to the authenticated user; set scope to project to create a task shared with the project. The request uses a flat payload, while the response returns the saved task with its issue template and normalized schedule nested under template and schedule.
Responses
200
Task created; the response contains its new numeric ID.
idintegerrequiredCreated or updated recurring task ID.
{
"id": 1
}
400
Invalid ID, payload, frequency, or schedule field.
messagestringHuman-readable validation or access error.
codeintegerMantisBT error code when supplied.
localizedstringLocalized error text when supplied.
Returns personal recurring tasks owned by the authenticated user. The endpoint always returns the pagination envelope used by this route: tasks contains the current page and pagination describes the clamped page and page size.
Parameters
Name
In
Type
Description
page
query
integer
One-based page number. Values below 1 are treated as 1.
per_page
query
integer
Number of tasks per page; the implementation clamps this to 1–100.
Responses
200
Personal tasks and pagination metadata.
tasksobject[]required
idintegerrequiredRecurring task ID.
namestringrequiredDisplay name.
owner_idintegerrequiredUser who owns the task.
scopeintegerrequired0 for personal, 1 for project scope.01
project_idintegerrequiredAssociated project ID.
reporter_idintegerrequiredReporter ID used when creating issues.
reporterobjectReporter account reference when populated by the surrounding API layer.
enabledintegerrequiredWhether the task can execute; responses serialize this database flag as 0 or 1.01
Returns a task visible to the authenticated user. The plugin converts stored UTC schedule values to the schedule user's local time and removes custom fields that are no longer valid for the project.
Parameters
Name
In
Type
Description
idrequired
path
integer · int32
Positive numeric ID of the recurring task.
Responses
200
The recurring task.
idintegerrequiredRecurring task ID.
namestringrequiredDisplay name.
owner_idintegerrequiredUser who owns the task.
scopeintegerrequired0 for personal, 1 for project scope.01
project_idintegerrequiredAssociated project ID.
reporter_idintegerrequiredReporter ID used when creating issues.
reporterobjectReporter account reference when populated by the surrounding API layer.
enabledintegerrequiredWhether the task can execute; responses serialize this database flag as 0 or 1.01
Updates an existing task. Fields omitted from the flat payload retain their current values. The operation can move a task between projects or convert its personal/project scope when the caller has the required permissions; project_id must still identify an enabled project.
Parameters
Name
In
Type
Description
idrequired
path
integer · int32
Positive numeric ID of the recurring task.
Responses
200
Task updated; the response contains its numeric ID.
idintegerrequiredCreated or updated recurring task ID.
{
"id": 1
}
400
Invalid ID, payload, frequency, or schedule field.
messagestringHuman-readable validation or access error.
codeintegerMantisBT error code when supplied.
localizedstringLocalized error text when supplied.
Executes an enabled task immediately using its saved issue template. A successful execution creates an issue and advances the counter; when the configured repeat limit is reached, the task is disabled. Failures are recorded in task history and may also disable the task when its reporter is no longer valid.
Parameters
Name
In
Type
Description
idrequired
path
integer · int32
Positive numeric ID of the recurring task.
Responses
204
Trigger accepted and completed without a response body.
400
Invalid ID, payload, frequency, or schedule field.
messagestringHuman-readable validation or access error.
codeintegerMantisBT error code when supplied.
localizedstringLocalized error text when supplied.
Lists tasks visible to the authenticated user for a project. By default it includes both project-scope tasks and the caller's personal tasks for that project. Results are sorted by task name and returned in a pagination envelope. Project ID 0 is not a valid project; the implementation also supports MantisBT's all-projects sentinel where applicable.
Parameters
Name
In
Type
Description
project_idrequired
path
integer · int32
Numeric project ID, or `0` (`ALL_PROJECTS`) to list tasks across accessible projects.
page
query
integer
One-based page number. Values below 1 are treated as 1.
per_page
query
integer
Number of tasks per page; the implementation clamps this to 1–100.
Responses
200
Visible project tasks and pagination metadata.
tasksobject[]required
idintegerrequiredRecurring task ID.
namestringrequiredDisplay name.
owner_idintegerrequiredUser who owns the task.
scopeintegerrequired0 for personal, 1 for project scope.01
project_idintegerrequiredAssociated project ID.
reporter_idintegerrequiredReporter ID used when creating issues.
reporterobjectReporter account reference when populated by the surrounding API layer.
enabledintegerrequiredWhether the task can execute; responses serialize this database flag as 0 or 1.01
Creates a project-scope recurring task. The path project is copied into the request payload and the scope defaults to project when omitted. The caller must have the configured project-task permission.
Parameters
Name
In
Type
Description
project_idrequired
path
integer · int32
Numeric ID of the project whose tasks are read or created.
Responses
200
Task created; the response contains its new numeric ID.
idintegerrequiredCreated or updated recurring task ID.
{
"id": 1
}
400
Invalid ID, payload, frequency, or schedule field.
messagestringHuman-readable validation or access error.
codeintegerMantisBT error code when supplied.
localizedstringLocalized error text when supplied.