Skip to content
MantisDocs

API Reference

The Mantis REST API provides programmatic access to all deployment automation features. Use it to integrate Mantis with your CI/CD pipelines, custom tooling, or external systems.

Base URL

Section titled “Base URL”

All API endpoints are relative to your Mantis server’s base URL:

https://<your-mantis-server>/api/v1/

For local development:

http://localhost:3000/api/v1/

API Version

Section titled “API Version”

The current API version is v1. All endpoints are prefixed with /api/v1/.

Content Type

Section titled “Content Type”

The API accepts and returns JSON. Always include these headers:

Content-Type: application/json
Accept: application/json

Authentication

Section titled “Authentication”

All API endpoints require authentication. See the Authentication guide for details on:

  • JWT Bearer token authentication
  • API key authentication
  • Token refresh flows
  • Two-factor authentication (2FA)

OpenAPI Specification

Section titled “OpenAPI Specification”

The complete OpenAPI 3.1 specification is available at:

https://<your-mantis-server>/api-docs/openapi.json

You can use this specification with tools like:

Quick Example

Section titled “Quick Example”

Here’s a complete example of authenticating and listing deployments:

Terminal window
# 1. Login and get access token
curl -X POST https://your-mantis-server/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'


# Response includes access_token
{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": { ... }
}


# 2. Use token to access protected endpoints
curl https://your-mantis-server/api/v1/deployments \
  -H "Authorization: Bearer eyJhbGci..."

Rate Limiting

Section titled “Rate Limiting”

The API implements rate limiting to ensure fair usage:

  • General API endpoints: 100 requests per second per client IP, with a burst allowance of 200
  • Authentication endpoints: 10 failed login attempts per minute per IP (successful logins are never counted; lockout triggers on failed attempts only)

When rate limited, you’ll receive a 429 Too Many Requests response with a Retry-After header. See the Error Handling guide for the exact response bodies and headers returned by each limiter.

Pagination

Section titled “Pagination”

List endpoints support pagination with these query parameters:

  • page - Page number (1-indexed, default: 1)
  • limit - Items per page (default: 50, max: 100)

See the Pagination guide for details.

Error Handling

Section titled “Error Handling”

The API returns consistent error responses. See the Error Handling guide for all error codes and troubleshooting.

API Reference Pages

Section titled “API Reference Pages”

This guide documents the most common API workflows:

Need Help?

Section titled “Need Help?”