developers
REST API reference
A small, stable JSON API to pull assets and findings, triage them, and launch scans. It's the same API the MCP server uses — everything below works from your editor or CI.
Base URL & authentication
The hosted API base is https://api.mustersecurity.com (self-hosted instances use their own domain under /api/v1). Every request uses a bearer token — create a key under Account → API keys. Each key is scoped to one organization and carries your role there, so it can only read and act on that org.
https://api.mustersecurity.comAuthorization: Bearer mus_xxxxxxxxxxxxxxxxxxxxxxxx
MUSTER_API_KEY is used in the samples below). Revoke it anytime from Account → API keys. It stops working if you leave the org.Prefer a machine-readable contract? The full OpenAPI 3.1 spec is published at /api/v1/openapi.json — point codegen, Postman, or an AI agent at it.
Pagination
Every list endpoint pages the same way: limit and offset query params, and a flat response envelope. The collection key matches the resource (findings, scans, assets).
| parameter | type | description |
|---|---|---|
limit | integer | Page size — default 25, max 100. |
offset | integer | Number of results to skip (default 0). |
{
"findings": [ /* … this page … */ ],
"count": 25, // items on THIS page
"total": 214, // across all pages
"limit": 25,
"offset": 0,
"has_more": true // another page exists
}Walk pages by adding limit to offset until has_more is false.
/orgsList organizations
Returns
organizations array (always exactly one).curl https://api.mustersecurity.com/orgs \ -H "Authorization: Bearer $MUSTER_API_KEY"
{
"organizations": [
{ "id": 1, "name": "Acme Inc.", "slug": "acme" }
]
}/orgs/:id/assetsList assets
Path parameters
| parameter | type | description |
|---|---|---|
id* | integer | The organization id. |
Query parameters
| parameter | type | description |
|---|---|---|
limit | integer | Page size (default 25, max 100). |
offset | integer | Skip this many results for pagination (default 0). |
Returns
assets array plus count (this page), total, limit, offset, and has_more.curl https://api.mustersecurity.com/orgs/1/assets \ -H "Authorization: Bearer $MUSTER_API_KEY"
{
"assets": [
{
"id": 12,
"kind": "web_app",
"identifier": "https://app.acme.com",
"name": "Acme app",
"last_scanned_at": "2026-08-01T10:12:00Z"
}
],
"count": 1,
"total": 1,
"limit": 25,
"offset": 0,
"has_more": false
}/orgs/:id/findingsList findings
Path parameters
| parameter | type | description |
|---|---|---|
id* | integer | The organization id. |
Query parameters
| parameter | type | description |
|---|---|---|
severity | string | critical | high | medium | low | info |
status | string | Defaults to open. Use all for every status. |
engine | string | Filter by engine: code | web | deps | cloud | dns | contract. |
type | string | Filter by vulnerability type / rule id (e.g. H001). |
updated_since | string | ISO timestamp. Only findings changed since then — poll this to sync. |
limit | integer | Page size (default 25, max 100). |
offset | integer | Skip this many results for pagination (default 0). |
Returns
findings array plus count (this page), total, limit, offset, and has_more.curl https://api.mustersecurity.com/orgs/1/findings?severity=high&limit=50 \ -H "Authorization: Bearer $MUSTER_API_KEY"
{
"findings": [
{
"id": 4012,
"org_id": 1,
"title": "Order readable as another user",
"severity": "high",
"original_severity": "high",
"status": "open",
"exploitable": true,
"engine": "web",
"type": "broken_access_control",
"asset": { "id": 12, "kind": "web_app", "name": "Acme app" },
"remediation": "Verify order.userId === session.userId",
"url": "https://app.mustersecurity.com/orgs/acme/alerts?finding=4012",
"first_seen": "2026-07-30T09:00:00Z",
"last_seen": "2026-08-01T10:12:00Z",
"updated_at": "2026-08-01T10:12:00Z"
}
],
"count": 1,
"total": 1,
"limit": 50,
"offset": 0,
"has_more": false
}/findings/:idRetrieve a finding
Path parameters
| parameter | type | description |
|---|---|---|
id* | integer | The finding id. |
Returns
curl https://api.mustersecurity.com/findings/4012 \ -H "Authorization: Bearer $MUSTER_API_KEY"
{
"id": 4012,
"title": "Order readable as another user",
"severity": "high",
"status": "open",
"engine": "web",
"type": "broken_access_control",
"description": "...",
"ai": { "impact": "...", "fix": "Verify order.userId === session.userId" },
"first_seen": "2026-07-30T09:00:00Z",
"last_seen": "2026-08-01T10:12:00Z"
}/findings/:idUpdate a finding
Path parameters
| parameter | type | description |
|---|---|---|
id* | integer | The finding id. |
Body parameters
| parameter | type | description |
|---|---|---|
status* | string | One of open, acknowledged, resolved, false_positive. |
note | string | Optional. Recorded on the finding as an audit trail (e.g. "fixed in PR #142"). |
Returns
id and new status.curl -X PATCH https://api.mustersecurity.com/findings/4012 \ -H "Authorization: Bearer $MUSTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"status": "resolved", "note": "fixed in PR #142"}'
{ "id": 4012, "status": "resolved" }/orgs/:id/findingsBulk update findings
Path parameters
| parameter | type | description |
|---|---|---|
id* | integer | The organization id. |
Body parameters
| parameter | type | description |
|---|---|---|
ids* | integer[] | Finding ids to update (from /orgs/:id/findings). Up to 1,000 unique ids per request; split larger sets into several calls. |
status* | string | One of open, acknowledged, resolved, false_positive. |
note | string | Optional. Recorded on each finding that changed as an audit trail. Up to 2,000 characters; longer notes are truncated. |
Returns
status applied, requested (unique ids sent), updated (how many changed), and updated_ids.curl -X PATCH https://api.mustersecurity.com/orgs/1/findings \ -H "Authorization: Bearer $MUSTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"ids": [4012, 4013, 4020], "status": "false_positive", "note": "internal test host"}'
{
"status": "false_positive",
"requested": 3,
"updated": 2,
"updated_ids": [4012, 4020]
}/orgs/:id/scanLaunch scans
Path parameters
| parameter | type | description |
|---|---|---|
id* | integer | The organization id. |
Body parameters
| parameter | type | description |
|---|---|---|
asset_ids | integer[] | Scan only these assets (ids from /orgs/:id/assets). Takes precedence over all. |
all | boolean | Re-scan every asset. Omit to scan only never-scanned assets. |
Returns
launched and skipped scans, plus any errors.curl -X POST https://api.mustersecurity.com/orgs/1/scan \ -H "Authorization: Bearer $MUSTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"asset_ids": [8]}'
{ "launched": 3, "skipped": 0, "errors": [] }/orgs/:id/scansList scans
Path parameters
| parameter | type | description |
|---|---|---|
id* | integer | The organization id. |
Query parameters
| parameter | type | description |
|---|---|---|
limit | integer | Page size (default 25, max 100). |
offset | integer | Skip this many results for pagination (default 0). |
Returns
scans array plus count (this page), total, limit, offset, and has_more.curl https://api.mustersecurity.com/orgs/1/scans?limit=10 \ -H "Authorization: Bearer $MUSTER_API_KEY"
{
"scans": [
{
"id": 88,
"engine": "web",
"status": "success",
"name": "Web app scan of app.acme.com",
"findings": 3,
"created_at": "2026-08-01T10:00:00Z",
"updated_at": "2026-08-01T10:12:00Z"
}
],
"count": 1,
"total": 1,
"limit": 25,
"offset": 0,
"has_more": false
}/scans/:idRetrieve a scan
Path parameters
| parameter | type | description |
|---|---|---|
id* | integer | The scan id. |
Returns
curl https://api.mustersecurity.com/scans/88 \ -H "Authorization: Bearer $MUSTER_API_KEY"
{
"id": 88,
"org_id": 1,
"engine": "web",
"status": "success",
"name": "Web app scan of app.acme.com",
"num_lines": 721,
"findings": 3,
"created_at": "2026-08-01T10:00:00Z",
"updated_at": "2026-08-01T10:12:00Z"
}/orgs/:id/summaryOrganization summary
Path parameters
| parameter | type | description |
|---|---|---|
id* | integer | The organization id. |
Returns
open_findings, open_by_severity, assets, and last_scanned_at.curl https://api.mustersecurity.com/orgs/1/summary \ -H "Authorization: Bearer $MUSTER_API_KEY"
{
"org_id": 1,
"security_score": 85,
"open_findings": 4,
"open_by_severity": {
"critical": 0, "high": 1, "medium": 1,
"low": 0, "info": 1, "gas": 1
},
"assets": 6,
"last_scanned_at": "2026-08-01T10:12:00Z"
}Errors
Errors return the appropriate HTTP status with a JSON body carrying a human error message and a stable machine code you can branch on — the code never changes even if the message is reworded.
{ "error": "This key isn't scoped to that organization.", "code": "forbidden_org_scope" }| parameter | type | description |
|---|---|---|
200 | success | Request succeeded. |
400 · invalid_request | error | Invalid parameters (e.g. an unknown status value). |
401 · unauthorized | error | Missing or invalid API key. |
402 · upgrade_required | error | Findings data and triage require a paid plan. |
403 · forbidden_org_scope | error | The key isn't scoped to that organization. |
403 · forbidden_role | error | The key's role can't perform this action (needs member+). |
404 · not_found | error | No such organization, finding, or scan. |
429 · rate_limited | error | Too many requests — back off and retry after the reset. |
Rate limits
Requests are limited per key. Every response carries the current budget in headers, so you can pace yourself without guessing. On a 429, wait until X-RateLimit-Reset before retrying.
| parameter | type | description |
|---|---|---|
X-RateLimit-Limit | header | Requests allowed in the current window. |
X-RateLimit-Remaining | header | Requests left in the current window. |
X-RateLimit-Reset | header | Unix time when the window resets. |
Idempotency
Mutating POSTs (currently POST /orgs/:id/scan) accept an Idempotency-Key header. Send a unique value per logical action and a safely-retried call returns the original result instead of launching a second scan — so a network blip never double-triggers work.
curl -X POST https://api.mustersecurity.com/orgs/1/scan \ -H "Authorization: Bearer $MUSTER_API_KEY" \ -H "Idempotency-Key: 3f9a-run-nightly-2026-08-01" \ -H "Content-Type: application/json" \ -d '{"all": true}'