Skip to main content

​
Base URL

All API requests are made to:

​
Authentication

The MindFort API uses Bearer token authentication. Include your MindFort API key in the Authorization header of every request:
You can generate API keys from the MindFort Dashboard under Settings > API Keys.

​
Rate Limits

  • Per-client limit: 60 requests per minute
  • Global limit: 100 requests per minute
When rate-limited, responses include a Retry-After: 60 header. The API returns HTTP 429 with an error message.

​
API Surface

The public REST API exposes the approved organization-scoped product surface:
  • list, get, create, update, and confirmed deletion of targets
  • create, rotate, inspect metadata for, and delete test credentials
  • read coverage checks and aggregate coverage
  • discover candidate targets and manage discovery suggestions when enabled
  • run, list, inspect, and cancel assessments
  • list and get findings; update lifecycle status; override severity; retest
  • manage finding comments and inspect patch summaries and counts
  • read finding analytics, security metrics, aging, remediation, SLA, and health scores
  • create, list, poll, and download reports
Use the endpoint reference for request and response schemas, query parameters, and examples.
The API does not expose target-verification operations, billing administration, API-key administration, organization membership, or role administration. Complete those workflows in the MindFort Dashboard.

​
REST and MCP

REST and MCP share organization-scoping rules and core resource contracts, but their available operations, authentication, and pagination differ. Assessment schedule management is available through MCP; it has no public REST routes. The MCP catalog is explicit and may omit feature-gated tools or schema variants that are unavailable to the selected organization. See the MCP guide.

​
Target and Credential Rules

Targets are scoped to the authenticated organization:
  • web_app and api targets require an HTTP(S) web_domain.
  • network targets require an ip_address and the network-targets organization feature.
  • Targets created through REST or MCP begin unverified. Complete domain ownership or network verification in the dashboard before starting active testing.
  • Target URLs containing embedded user:password@host credentials are rejected.
Credential list and detail reads return metadata only, omitting passwords, API-key values, and TOTP seeds. Dedicated code-check endpoints can return temporary authentication codes or login URLs; email provisioning returns a pending inbox ID for credential creation. An api_key credential is valid only for an api target. Before adding one, set nonblank target-level api_auth_instructions that describe the validation route, method, request shape, key placement, and expected successful response.

​
Coverage

Coverage shows security scenarios tested across assessments. Use GET /v1/coverage to list checks and GET /v1/coverage/overview for aggregate counts, optionally filtered by target_id. The current states are covered, failing, incomplete, in_progress, and not_run. Responses include scenario details, run summaries, and related findings. Coverage is read-only; assessments maintain the checks and run history. See Coverage.

​
Discovery

When Discovery is enabled, use /v1/discovery to inspect its status, configure context and schedules, start runs, and accept or dismiss candidate targets. See Target discovery for the operation list.

​
Pagination

REST list endpoints use two pagination styles:
  • GET /v1/assessments uses cursor pagination. Pass the returned pagination.next_cursor value as the next request’s cursor parameter until no next cursor is returned.
  • Target, credential, coverage, finding, comment, patch, and report collections use the pagination fields documented on their endpoint schemas. Offset-based responses include a total; cursor-based responses return next_cursor when another page is available.
Do not construct or modify cursor values. Pass each cursor back unchanged with the same filters.

​
Error Format

Errors follow a consistent public JSON structure:
The code field is present for recognized actionable failures. Responses may also include safe field validation details. Include the request_id when contacting support. Examples of stable error codes include:
  • target_not_verified
  • api_auth_instructions_required
  • assessment_already_running
  • assessment_credits_insufficient
  • assessment_queue_loading
  • retest_already_running
Retryable responses may include Retry-After. If you receive HTTP 429 Too Many Requests, wait for the interval specified by that header before retrying and reduce request frequency. Coordinate polling across integrations that share your organization.

​
Component IDs

Several API endpoints require UUIDs for targets, findings, assessments, reports, and other resources. Below is where to find each ID in the MindFort dashboard.

​
Targets

Navigate to Target Inventory and click on a target. The Target ID is displayed on the target’s detail page.

​
Findings

Use GET /v1/findings or open a finding in the dashboard. The Finding ID identifies a specific vulnerability for detail, comment, status, severity, and retest requests. Filter list results with status, assessment_id, exclude_secured, target_id, and severity. See Findings API for parameter details and dashboard mapping.

​
Assessments

Open Assessments, select a run, and copy the Assessment ID from the URL or detail view. Use it as assessment_id when listing findings for that run only. Use stage_progress in assessment detail to track each stage. NOT_STARTED means the stage has no recorded state; RUNNING or ACTIVE indicates current work; other values are terminal outcomes. Failed runs may include a failure_reason explaining the problem.

​
Credentials

List credentials under a target to obtain credential IDs and safe metadata. Use credential IDs when running authenticated assessments or rotating/deleting a credential. Secret values are never returned.

​
Reports

Create a report with POST /v1/reports, then poll GET /v1/reports/{report_id} until it is ready and call GET /v1/reports/{report_id}/download for a short-lived download URL.

​
Content Type

All endpoints accept and return application/json. Requests with a JSON body must include:

​
Plan and role access

An API key does not bypass feature, billing, or permission checks. Reporting and retesting require an upgraded plan. Discovery and network-target capabilities also require the corresponding organization features.