\r \r

Mantis Manager Skill (Enhanced)\r

\r

🔐 Base URL & Token Resolution\r

\r

Base URL Resolution\r

Base URL precedence (highest to lowest):\r

1. temporary_base_url — one-time use URL for specific operations\r
2. user_base_url — user-defined URL for the current session\r
3. MANTIS_BASE_URL — environment default URL\r \r This allows you to:\r

• Switch between multiple Mantis instances dynamically\r
• Test against staging/production environments\r
• Work with different client instances without changing config\r \r Example:\r

// Default: uses MANTIS_BASE_URL from environment\r
GET {{resolved_base_url}}/issues\r
\r
// Override for one operation:\r
temporary_base_url = "https://mantis-staging.example.com/api/rest"\r
GET {{resolved_base_url}}/issues\r
\r
// Override for session:\r
user_base_url = "https://client-mantis.example.com/api/rest"\r
GET {{resolved_base_url}}/issues\r
```\r
\r
### Token Resolution\r
Token precedence (highest to lowest):\r
1. `temporary_token` — one-time use token for specific operations\r
2. `user_token` — user-defined token for the current session\r
3. `MANTIS_API_TOKEN` — environment default token\r
\r
Environment variables are handled via standard OpenClaw metadata: `requires.env` declares **required** variables (`MANTIS_BASE_URL`, `MANTIS_API_TOKEN`). Any other environment variables you use for Mantis should be treated as normal process env vars and are not modeled as special OpenClaw metadata fields.\r
\r
### Authentication Headers\r
**All API requests must include:**\r
\r
```\r
Authorization: Bearer {{resolved_token}}\r
Content-Type: application/json\r
```\r
\r
**Note:** The `{{resolved_base_url}}` and `{{resolved_token}}` are determined at runtime based on the precedence rules above.\r
\r
---\r
\r
## 📌 Notation Used in Examples\r
\r
Throughout this documentation:\r
- `{{MANTIS_BASE_URL}}` refers to the **resolved base URL** (could be temporary_base_url, user_base_url, or env MANTIS_BASE_URL)\r
- `{{resolved_token}}` refers to the **resolved token** (could be temporary_token, user_token, or env MANTIS_API_TOKEN)\r
- All endpoints use the pattern: `{{MANTIS_BASE_URL}}/resource/path`\r
\r
**Important:** Always use the resolution logic to determine the actual URL and token at runtime.\r
\r
---\r
\r
## 🔄 Context Management\r
\r
> The `temporary_*` and `user_*` names here are **runtime context variables used by the skill logic**, not OpenClaw metadata fields. OpenClaw does **not** define an `optional.context` metadata key; context is resolved dynamically at runtime as described below.\r
\r
### Setting Temporary Values (One-Time Use)\r
\r
**User queries:**\r
- "Use https://staging.mantis.com/api/rest for this request"\r
- "Connect to production instance for this operation"\r
- "Use token ABC123 just this once"\r
\r
**Action:**\r
```\r
Set temporary_base_url = "https://staging.mantis.com/api/rest"\r
Set temporary_token = "ABC123"\r
... perform operation ...\r
Clear temporary_base_url\r
Clear temporary_token\r
```\r
\r
**Behavior:** Temporary values are automatically cleared after one use.\r
\r
### Setting Session Values (Current Session)\r
\r
**User queries:**\r
- "Switch to client XYZ's Mantis instance"\r
- "Use my personal API token for all requests"\r
- "Connect to staging environment"\r
\r
**Action:**\r
```\r
Set user_base_url = "https://client-xyz.mantis.com/api/rest"\r
Set user_token = "personal_token_123"\r
... perform multiple operations ...\r
// Values persist for the entire session\r
```\r
\r
**Behavior:** Session values persist until explicitly cleared or session ends.\r
\r
### Clearing Context Values\r
\r
**User queries:**\r
- "Reset to default Mantis instance"\r
- "Clear my custom token"\r
- "Go back to environment defaults"\r
\r
**Action:**\r
```\r
Clear user_base_url\r
Clear user_token\r
// Now uses MANTIS_BASE_URL and MANTIS_API_TOKEN from environment\r
```\r
\r
### Viewing Current Context\r
\r
**User queries:**\r
- "What Mantis instance am I connected to?"\r
- "Show current API configuration"\r
- "Which token am I using?"\r
\r
**Response should show:**\r
```\r
Current Context:\r
- Base URL: https://client-xyz.mantis.com/api/rest (user_base_url)\r
- Token: user_t***123 (user_token)\r
- Fallback Base URL: https://default.mantis.com/api/rest (MANTIS_BASE_URL)\r
- Fallback Token: env_t***789 (MANTIS_API_TOKEN)\r
```\r
\r
### Use Cases\r
\r
#### Multi-Instance Management\r
```\r
// Check production issue\r
Set temporary_base_url = "https://prod.mantis.com/api/rest"\r
Get issue 123\r
\r
// Check staging issue  \r
Set temporary_base_url = "https://staging.mantis.com/api/rest"\r
Get issue 123\r
\r
// Compare results\r
```\r
\r
#### Client Switching\r
```\r
// Switch to Client A\r
Set user_base_url = "https://clienta.mantis.com/api/rest"\r
Set user_token = "clienta_token"\r
List all projects\r
Get issues for project 5\r
\r
// Switch to Client B\r
Set user_base_url = "https://clientb.mantis.com/api/rest"\r
Set user_token = "clientb_token"\r
List all projects\r
Get issues for project 3\r
```\r
\r
#### Admin Operations with Impersonation\r
```\r
// Connect to main instance as admin\r
Set user_token = "admin_token"\r
\r
// Perform operation as specific user\r
Set temporary header: X-Impersonate-User = "john.doe"\r
Get user issues\r
\r
// Back to admin\r
Clear temporary header\r
```\r
\r
---\r
\r
## 🐞 ISSUES Operations\r
\r
### List Issues\r
**User queries:**\r
- "List all issues"\r
- "Get issues for project 5"\r
- "Get issues matching filter 10"\r
- "Show issues assigned to me"\r
- "Get unassigned issues"\r
\r
**Actions:**\r
```\r
GET {{MANTIS_BASE_URL}}/issues\r
```\r
\r
**Query Parameters:**\r
- `page_size` — number of issues per page (default: 50)\r
- `page` — page number (1-indexed)\r
- `filter_id` — ID of saved filter to apply\r
- `project_id` — filter by specific project\r
- `select` — comma-separated fields to return (e.g., "id,summary,status")\r
\r
**Special endpoints:**\r
```\r
GET {{MANTIS_BASE_URL}}/issues?filter_id={{filter_id}}\r
GET {{MANTIS_BASE_URL}}/projects/{{project_id}}/issues\r
```\r
\r
### Get Single Issue\r
**User queries:**\r
- "Show issue 123"\r
- "Get details for bug 456"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/issues/{{id}}\r
```\r
\r
### Create Issue\r
**User queries:**\r
- "Create issue with summary 'Login bug' and description 'Cannot login'"\r
- "Create bug in project 5 with priority high"\r
- "Create issue with attachments"\r
\r
**Action:**\r
```\r
POST {{MANTIS_BASE_URL}}/issues\r
```\r
\r
**Minimal body:**\r
```json\r
{\r
  "summary": "Issue summary",\r
  "description": "Detailed description",\r
  "category": {"name": "General"},\r
  "project": {"id": 1}\r
}\r
```\r
\r
**Full body (optional fields):**\r
```json\r
{\r
  "summary": "Issue summary",\r
  "description": "Detailed description",\r
  "steps_to_reproduce": "1. Do this\
2. Do that",\r
  "additional_information": "Extra info",\r
  "category": {"id": 1, "name": "General"},\r
  "project": {"id": 1},\r
  "priority": {"id": 30, "name": "normal"},\r
  "severity": {"id": 50, "name": "minor"},\r
  "status": {"id": 10, "name": "new"},\r
  "reproducibility": {"id": 10, "name": "always"},\r
  "handler": {"id": 5},\r
  "tags": [{"name": "bug"}, {"name": "ui"}],\r
  "custom_fields": [{"field": {"id": 1}, "value": "custom value"}],\r
  "due_date": "2026-12-31T23:59:59+00:00",\r
  "version": {"name": "1.0"},\r
  "target_version": {"name": "2.0"}\r
}\r
```\r
\r
**Create with attachments:**\r
```\r
POST {{MANTIS_BASE_URL}}/issues\r
```\r
Include `files` array in body with base64-encoded content.\r
\r
### Update Issue\r
**User queries:**\r
- "Update issue 123 status to resolved"\r
- "Change priority of bug 456 to high"\r
- "Assign issue 789 to user 10"\r
\r
**Action:**\r
```\r
PATCH {{MANTIS_BASE_URL}}/issues/{{id}}\r
```\r
\r
**Example body:**\r
```json\r
{\r
  "status": {"name": "resolved"},\r
  "handler": {"id": 10},\r
  "priority": {"name": "high"},\r
  "summary": "Updated summary"\r
}\r
```\r
\r
### Delete Issue\r
**User queries:**\r
- "Delete issue 123"\r
- "Remove bug 456"\r
\r
**Action:**\r
```\r
DELETE {{MANTIS_BASE_URL}}/issues/{{id}}\r
```\r
\r
### Monitor/Unmonitor Issue\r
**User queries:**\r
- "Monitor issue 123"\r
- "Stop monitoring bug 456"\r
- "Add user 10 as monitor on issue 789"\r
\r
**Actions:**\r
```\r
POST   {{MANTIS_BASE_URL}}/issues/{{id}}/monitors\r
DELETE {{MANTIS_BASE_URL}}/issues/{{id}}/monitors\r
```\r
\r
**Body (for specific user):**\r
```json\r
{\r
  "user": {"id": 10}\r
}\r
```\r
\r
### Attach/Detach Tags\r
**User queries:**\r
- "Add tag 'critical' to issue 123"\r
- "Remove tag 'bug' from issue 456"\r
\r
**Actions:**\r
```\r
POST   {{MANTIS_BASE_URL}}/issues/{{id}}/tags\r
PATCH  {{MANTIS_BASE_URL}}/issues/{{id}}/tags\r
DELETE {{MANTIS_BASE_URL}}/issues/{{id}}/tags\r
```\r
\r
**Body:**\r
```json\r
{\r
  "tags": [\r
    {"name": "bug"},\r
    {"name": "critical"}\r
  ]\r
}\r
```\r
\r
### Add Issue Relationship\r
**User queries:**\r
- "Link issue 123 to issue 456 as duplicate"\r
- "Add parent relationship from 789 to 101"\r
\r
**Action:**\r
```\r
POST {{MANTIS_BASE_URL}}/issues/{{id}}/relationships\r
```\r
\r
**Body:**\r
```json\r
{\r
  "type": {"name": "duplicate-of"},\r
  "target_issue": {"id": 456}\r
}\r
```\r
\r
**Relationship types:**\r
- `duplicate-of`\r
- `related-to`\r
- `parent-of`\r
- `child-of`\r
- `has-duplicate`\r
\r
### Attach Files\r
**User queries:**\r
- "Attach file to issue 123"\r
- "Add screenshot to bug 456"\r
\r
**Action:**\r
```\r
POST {{MANTIS_BASE_URL}}/issues/{{id}}/files\r
```\r
\r
**Body:**\r
```json\r
{\r
  "files": [\r
    {\r
      "name": "screenshot.png",\r
      "content": "base64_encoded_content_here"\r
    }\r
  ]\r
}\r
```\r
\r
### Delete Attachment\r
**User queries:**\r
- "Delete attachment 789 from issue 123"\r
- "Remove file 101 from bug 456"\r
\r
**Action:**\r
```\r
DELETE {{MANTIS_BASE_URL}}/issues/{{issue_id}}/files/{{file_id}}\r
```\r
\r
### Issue Notes\r
\r
#### Add Note\r
**User queries:**\r
- "Add note to issue 123: 'This is fixed now'"\r
- "Add note with time tracking 2 hours"\r
- "Add private note to bug 456"\r
\r
**Action:**\r
```\r
POST {{MANTIS_BASE_URL}}/issues/{{id}}/notes\r
```\r
\r
**Body:**\r
```json\r
{\r
  "text": "Note content here",\r
  "view_state": {"name": "public"},\r
  "time_tracking": "PT2H30M"\r
}\r
```\r
\r
**With attachment:**\r
```json\r
{\r
  "text": "Note with file",\r
  "files": [\r
    {\r
      "name": "log.txt",\r
      "content": "base64_content"\r
    }\r
  ]\r
}\r
```\r
\r
#### Delete Note\r
**User queries:**\r
- "Delete note 55 from issue 123"\r
- "Remove comment 99 from bug 456"\r
\r
**Action:**\r
```\r
DELETE {{MANTIS_BASE_URL}}/issues/{{issue_id}}/notes/{{note_id}}\r
```\r
\r
---\r
\r
## 📁 PROJECTS Operations\r
\r
### List All Projects\r
**User queries:**\r
- "List all projects"\r
- "Show all projects"\r
- "Get projects"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/projects\r
```\r
\r
### Get Project by ID\r
**User queries:**\r
- "Show project 5"\r
- "Get details for project 10"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/projects/{{id}}\r
```\r
\r
### Create Project\r
**User queries:**\r
- "Create project named 'New Product'"\r
- "Add project with description 'Internal tools'"\r
\r
**Action:**\r
```\r
POST {{MANTIS_BASE_URL}}/projects\r
```\r
\r
**Body:**\r
```json\r
{\r
  "name": "Project Name",\r
  "description": "Project description",\r
  "enabled": true,\r
  "inherit_global": true,\r
  "view_state": {"name": "public"},\r
  "status": {"name": "development"}\r
}\r
```\r
\r
### Update Project\r
**User queries:**\r
- "Update project 5 description"\r
- "Change project 10 status to stable"\r
\r
**Action:**\r
```\r
PATCH {{MANTIS_BASE_URL}}/projects/{{id}}\r
```\r
\r
### Delete Project\r
**User queries:**\r
- "Delete project 5"\r
- "Remove project 10"\r
\r
**Action:**\r
```\r
DELETE {{MANTIS_BASE_URL}}/projects/{{id}}\r
```\r
\r
### Sub-Projects\r
\r
#### Get Sub-Projects\r
**User queries:**\r
- "Show sub-projects of project 5"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/projects/{{id}}/subprojects\r
```\r
\r
#### Create Sub-Project\r
**User queries:**\r
- "Create sub-project under project 5"\r
\r
**Action:**\r
```\r
POST {{MANTIS_BASE_URL}}/projects/{{id}}/subprojects\r
```\r
\r
**Body:**\r
```json\r
{\r
  "subproject": {"id": 10}\r
}\r
```\r
\r
#### Delete Sub-Project\r
**Action:**\r
```\r
DELETE {{MANTIS_BASE_URL}}/projects/{{id}}/subprojects/{{subproject_id}}\r
```\r
\r
### Project Users\r
\r
#### Get Project Users\r
**User queries:**\r
- "Show users in project 5"\r
- "List members of project 10"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/projects/{{id}}/users\r
```\r
\r
#### Add User to Project\r
**User queries:**\r
- "Add user 20 to project 5 as developer"\r
\r
**Action:**\r
```\r
POST {{MANTIS_BASE_URL}}/projects/{{id}}/users\r
```\r
\r
**Body:**\r
```json\r
{\r
  "user": {"id": 20},\r
  "access_level": {"name": "developer"}\r
}\r
```\r
\r
**Access levels:**\r
- `viewer` (10)\r
- `reporter` (25)\r
- `updater` (40)\r
- `developer` (55)\r
- `manager` (70)\r
- `administrator` (90)\r
\r
#### Delete User from Project\r
**Action:**\r
```\r
DELETE {{MANTIS_BASE_URL}}/projects/{{project_id}}/users/{{user_id}}\r
```\r
\r
### Project Versions\r
\r
#### Get Versions\r
**User queries:**\r
- "Show versions of project 5"\r
- "List releases for project 10"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/projects/{{id}}/versions\r
```\r
\r
#### Create Version\r
**User queries:**\r
- "Create version 2.0 for project 5"\r
- "Add release 1.5 to project 10"\r
\r
**Action:**\r
```\r
POST {{MANTIS_BASE_URL}}/projects/{{id}}/versions\r
```\r
\r
**Body:**\r
```json\r
{\r
  "name": "2.0",\r
  "description": "Major release",\r
  "released": true,\r
  "obsolete": false,\r
  "timestamp": "2026-06-01T00:00:00+00:00"\r
}\r
```\r
\r
#### Update Version\r
**Action:**\r
```\r
PATCH {{MANTIS_BASE_URL}}/projects/{{project_id}}/versions/{{version_id}}\r
```\r
\r
#### Delete Version\r
**Action:**\r
```\r
DELETE {{MANTIS_BASE_URL}}/projects/{{project_id}}/versions/{{version_id}}\r
```\r
\r
---\r
\r
## 👥 USERS Operations\r
\r
### Get My User Info\r
**User queries:**\r
- "Show my user info"\r
- "Get my profile"\r
- "Who am I?"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/users/me\r
```\r
\r
### Get User by ID\r
**User queries:**\r
- "Show user 10"\r
- "Get info for user 25"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/users/{{id}}\r
```\r
\r
### Get User by Username\r
**User queries:**\r
- "Find user 'john.doe'"\r
- "Get user with username 'admin'"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/users?name={{username}}\r
```\r
\r
### Create User\r
**User queries:**\r
- "Create user 'jane.smith' with email '[email protected]'"\r
- "Add new user"\r
\r
**Action:**\r
```\r
POST {{MANTIS_BASE_URL}}/users\r
```\r
\r
**Minimal body:**\r
```json\r
{\r
  "username": "jane.smith",\r
  "email": "[email protected]",\r
  "access_level": {"name": "reporter"}\r
}\r
```\r
\r
**Full body:**\r
```json\r
{\r
  "username": "jane.smith",\r
  "password": "SecurePass123!",\r
  "real_name": "Jane Smith",\r
  "email": "[email protected]",\r
  "access_level": {"name": "developer"},\r
  "enabled": true,\r
  "protected": false\r
}\r
```\r
\r
### Update User\r
**User queries:**\r
- "Update user 10 email to '[email protected]'"\r
- "Change user 25 access level to developer"\r
\r
**Action:**\r
```\r
PATCH {{MANTIS_BASE_URL}}/users/{{id}}\r
```\r
\r
**Body:**\r
```json\r
{\r
  "real_name": "Updated Name",\r
  "email": "[email protected]",\r
  "access_level": {"name": "developer"},\r
  "enabled": false\r
}\r
```\r
\r
### Reset User Password\r
**User queries:**\r
- "Reset password for user 10"\r
\r
**Action:**\r
```\r
PUT {{MANTIS_BASE_URL}}/users/{{id}}/reset-password\r
```\r
\r
**Body:**\r
```json\r
{\r
  "password": "NewSecurePassword123!"\r
}\r
```\r
\r
### Delete User\r
**User queries:**\r
- "Delete user 10"\r
- "Remove user 'john.doe'"\r
\r
**Action:**\r
```\r
DELETE {{MANTIS_BASE_URL}}/users/{{id}}\r
```\r
\r
---\r
\r
## 🔍 FILTERS Operations\r
\r
### Get All Filters\r
**User queries:**\r
- "List all filters"\r
- "Show my saved filters"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/filters\r
```\r
\r
### Get Filter by ID\r
**User queries:**\r
- "Show filter 5"\r
- "Get details for filter 10"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/filters/{{id}}\r
```\r
\r
### Delete Filter\r
**User queries:**\r
- "Delete filter 5"\r
- "Remove saved filter 10"\r
\r
**Action:**\r
```\r
DELETE {{MANTIS_BASE_URL}}/filters/{{id}}\r
```\r
\r
---\r
\r
## 🔐 TOKEN MANAGEMENT\r
\r
### Create Token for Self\r
**User queries:**\r
- "Create my API token"\r
- "Generate token for me"\r
- "Create new token named 'automation'"\r
\r
**Action:**\r
```\r
POST {{MANTIS_BASE_URL}}/user_tokens\r
```\r
\r
**Body:**\r
```json\r
{\r
  "name": "automation_token",\r
  "date_expiry": "2027-12-31T23:59:59+00:00"\r
}\r
```\r
\r
### Delete Token for Self\r
**User queries:**\r
- "Delete my token"\r
- "Revoke my API token"\r
\r
**Action:**\r
```\r
DELETE {{MANTIS_BASE_URL}}/user_tokens/{{token_id}}\r
```\r
\r
### Create Token for Another User\r
**User queries:**\r
- "Create token for user 10"\r
- "Generate API token for user 'john.doe'"\r
\r
**Action:**\r
```\r
POST {{MANTIS_BASE_URL}}/users/{{user_id}}/tokens\r
```\r
\r
**Body:**\r
```json\r
{\r
  "name": "user_token",\r
  "date_expiry": "2027-12-31T23:59:59+00:00"\r
}\r
```\r
\r
### Delete Token for Another User\r
**Action:**\r
```\r
DELETE {{MANTIS_BASE_URL}}/users/{{user_id}}/tokens/{{token_id}}\r
```\r
\r
---\r
\r
## ⚙️ CONFIG Operations\r
\r
### Get Single Configuration Option\r
**User queries:**\r
- "Get config option 'bug_report_page_fields'"\r
- "Show configuration for 'default_category_for_moves'"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/config/{{option}}\r
```\r
\r
### Get Multiple Configuration Options\r
**User queries:**\r
- "Get configs for project 5"\r
- "Show all config options"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/config\r
```\r
\r
**Query parameters:**\r
- `option` — specific option name\r
- `project_id` — filter by project\r
- `user_id` — filter by user\r
\r
### Set Configuration Option\r
**User queries:**\r
- "Set config 'allow_signup' to true"\r
- "Update config option"\r
\r
**Action:**\r
```\r
PATCH {{MANTIS_BASE_URL}}/config\r
```\r
\r
**Body:**\r
```json\r
{\r
  "configs": [\r
    {\r
      "option": "allow_signup",\r
      "value": "1"\r
    }\r
  ]\r
}\r
```\r
\r
---\r
\r
## 🌍 LOCALIZATION Operations\r
\r
### Get Localized String\r
**User queries:**\r
- "Get localized string 'status_new'"\r
- "Translate 'priority_high' to French"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/lang/{{string}}\r
```\r
\r
**Query parameter:**\r
- `language` — language code (e.g., 'fr', 'en', 'de')\r
\r
### Get Multiple Localized Strings\r
**User queries:**\r
- "Get all status translations"\r
- "Get localized strings for priorities"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/lang\r
```\r
\r
**Query parameters:**\r
- `strings` — comma-separated list of string keys\r
- `language` — language code\r
\r
---\r
\r
## 🔒 IMPERSONATION\r
\r
### Get User Info with Impersonation\r
**User queries:**\r
- "Impersonate user 10 and get their info"\r
- "Get info as user 'john.doe'"\r
\r
**Action:**\r
```\r
GET {{MANTIS_BASE_URL}}/users/me\r
```\r
\r
**Header:**\r
```\r
X-Impersonate-User: {{username_or_id}}\r
```\r
\r
---\r
\r
## ⚠️ Error Handling\r
\r
Handle HTTP errors gracefully:\r
\r
**401 Unauthorized:**\r
- Token is invalid or expired\r
- Action: Inform user to check `MANTIS_API_TOKEN` or provide valid `temporary_token`\r
\r
**403 Forbidden:**\r
- User doesn't have permission for this operation\r
- Action: Inform user about insufficient permissions\r
\r
**404 Not Found:**\r
- Resource (issue, project, user, etc.) doesn't exist\r
- Action: Inform user that the requested resource was not found\r
\r
**422 Unprocessable Entity:**\r
- Validation error in request body\r
- Action: Show validation errors from response and guide user\r
\r
**500 Internal Server Error:**\r
- Server-side error\r
- Action: Inform user of server error and suggest retrying later\r
\r
**General error response format:**\r
```json\r
{\r
  "message": "Error description",\r
  "code": 1234,\r
  "localized": "Localized error message"\r
}\r
```\r
\r
---\r
\r
## 📋 Best Practices\r
\r
### Pagination\r
- Always support `page_size` and `page` parameters for list operations\r
- Default page size: 50\r
- Inform user when results are paginated\r
\r
### Field Selection\r
- Use `select` parameter to return only needed fields\r
- Example: `select=id,summary,status,priority`\r
- Reduces bandwidth and improves performance\r
\r
### Filtering\r
- Use `filter_id` to apply saved filters\r
- Combine with pagination for large datasets\r
- Consider project-specific filtering with `project_id`\r
\r
### Attachments\r
- Files must be base64-encoded\r
- Include filename and content in request\r
- Verify file size limits (check Mantis config)\r
\r
### Time Tracking\r
- Use ISO 8601 duration format: `PT2H30M` (2 hours 30 minutes)\r
- Can be added to notes for time tracking\r
\r
### Date Formats\r
- Use ISO 8601: `2026-12-31T23:59:59+00:00`\r
- Include timezone for accuracy\r
\r
### Custom Fields\r
- Check project configuration for available custom fields\r
- Reference by field ID in requests\r
\r
### Relationships\r
- Verify relationship types supported by your Mantis version\r
- Some relationships auto-create reciprocal links\r
\r
---\r
\r
## 🚀 Quick Examples\r
\r
### Create and Monitor Issue\r
```\r
1. POST /issues with summary and description\r
2. POST /issues/{{new_id}}/monitors to monitor\r
```\r
\r
### Assign Issue and Add Note\r
```\r
1. PATCH /issues/{{id}} with handler\r
2. POST /issues/{{id}}/notes with assignment comment\r
```\r
\r
### Create Project with Version\r
```\r
1. POST /projects with project details\r
2. POST /projects/{{id}}/versions with version info\r
```\r
\r
### User Management Flow\r
```\r
1. POST /users to create user\r
2. POST /projects/{{id}}/users to add to project\r
3. POST /users/{{id}}/tokens to create API token\r
```\r
\r
---\r
\r
## 🎯 Advanced Use Cases\r
\r
### Bulk Issue Updates\r
When updating multiple issues:\r
- Loop through issue IDs\r
- Use PATCH for each issue\r
- Collect results and report summary\r
\r
### Filter-Based Operations\r
Get all high-priority bugs:\r
```\r
1. GET /filters to find priority filter ID\r
2. GET /issues?filter_id={{filter_id}}&page_size=100\r
3. Process paginated results\r
```\r
\r
### Project Migration\r
Copy project structure:\r
```\r
1. GET /projects/{{source_id}} to get project details\r
2. GET /projects/{{source_id}}/versions for versions\r
3. POST /projects to create new project\r
4. POST /projects/{{new_id}}/versions for each version\r
```\r
\r
### User Audit\r
Track user activity:\r
```\r
1. GET /issues?reporter_id={{user_id}}\r
2. GET /issues?handler_id={{user_id}}\r
3. GET /issues?monitor_id={{user_id}}\r
4. Compile activity report\r
```\r
\r
### Multi-Instance Management\r
Work with multiple Mantis instances:\r
```\r
// Scenario: Compare issue status across environments\r
\r
1. Check production:\r
   Set temporary_base_url = "https://prod.mantis.com/api/rest"\r
   Set temporary_token = "prod_token"\r
   GET /issues/123\r
   Record status\r
\r
2. Check staging:\r
   Set temporary_base_url = "https://staging.mantis.com/api/rest"\r
   Set temporary_token = "staging_token"\r
   GET /issues/123\r
   Record status\r
\r
3. Compare and report differences\r
```\r
\r
### Cross-Instance Synchronization\r
Sync data between instances:\r
```\r
// Scenario: Clone project from one instance to another\r
\r
1. Connect to source instance:\r
   Set user_base_url = "https://source.mantis.com/api/rest"\r
   Set user_token = "source_token"\r
   GET /projects/5 (get project details)\r
   GET /projects/5/versions (get versions)\r
   GET /projects/5/users (get users)\r
\r
2. Connect to target instance:\r
   Set user_base_url = "https://target.mantis.com/api/rest"\r
   Set user_token = "target_token"\r
   POST /projects (create project)\r
   POST /projects/{{new_id}}/versions (create versions)\r
   POST /projects/{{new_id}}/users (add users)\r
\r
3. Report sync results\r
```\r
\r
### Client-Specific Operations\r
Manage multiple client instances:\r
```\r
// Scenario: Daily status report for all clients\r
\r
For each client in [ClientA, ClientB, ClientC]:\r
  1. Set user_base_url = client.mantis_url\r
  2. Set user_token = client.api_token\r
  3. GET /issues?filter_id=1 (get today's issues)\r
  4. Collect statistics\r
  5. Clear context\r
\r
Generate consolidated report\r
```\r
\r
---\r
\r
## 📚 Resources\r
\r
- **Mantis API Documentation**: Check your Mantis instance at `{{MANTIS_BASE_URL}}/api/rest/swagger.yaml`\r
- **Issue Statuses**: new, feedback, acknowledged, confirmed, assigned, resolved, closed\r
- **Priorities**: none, low, normal, high, urgent, immediate\r
- **Severities**: feature, trivial, text, tweak, minor, major, crash, block\r
- **Access Levels**: 10=viewer, 25=reporter, 40=updater, 55=developer, 70=manager, 90=administrator\r
\r
---\r
\r
## ✅ Skill Capabilities Summary\r
\r
This skill enables you to:\r
\r
### Core Operations\r
- ✅ Full CRUD operations on issues\r
- ✅ Manage issue relationships, tags, monitors\r
- ✅ Add notes with time tracking and attachments\r
- ✅ Full project management (create, update, delete)\r
- ✅ Manage sub-projects, versions, and project users\r
- ✅ User management (CRUD, password reset)\r
- ✅ API token management (create, delete for self and others)\r
- ✅ Filter management and filtered queries\r
- ✅ Configuration management\r
- ✅ Localization support\r
- ✅ Impersonation capabilities\r
\r
### Advanced Features\r
- ✅ **Dynamic instance switching** — Switch between multiple Mantis instances on-the-fly\r
- ✅ **Context-aware URL resolution** — temporary_base_url → user_base_url → MANTIS_BASE_URL\r
- ✅ **Context-aware token resolution** — temporary_token → user_token → MANTIS_API_TOKEN\r
- ✅ **Multi-instance management** — Manage multiple clients/environments simultaneously\r
- ✅ **Cross-instance operations** — Compare, sync, and migrate data between instances\r
- ✅ Comprehensive error handling\r
- ✅ Pagination and field selection\r
- ✅ Advanced workflows and bulk operations\r