Muster.

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.

base url
https://api.mustersecurity.com
auth header
Authorization: Bearer mus_xxxxxxxxxxxxxxxxxxxxxxxx
⚠
A key is shown once at creation — store it securely (an env var like 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).

parametertypedescription
limitintegerPage size — default 25, max 100.
offsetintegerNumber of results to skip (default 0).
list envelope
{
  "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.

GET/orgs

List organizations

Returns the single organization your API key is scoped to. Use its id in the other endpoints.

Returns

An object with an organizations array (always exactly one).
curl https://api.mustersecurity.com/orgs \
  -H "Authorization: Bearer $MUSTER_API_KEY"
example response
{
  "organizations": [
    { "id": 1, "name": "Acme Inc.", "slug": "acme" }
  ]
}
GET/orgs/:id/assets

List assets

Lists everything under protection in the organization — connected repositories, web apps/services, and cloud accounts.

Path parameters

parametertypedescription
id*integerThe organization id.

Query parameters

parametertypedescription
limitintegerPage size (default 25, max 100).
offsetintegerSkip this many results for pagination (default 0).

Returns

An 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"
example response
{
  "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
}
GET/orgs/:id/findings

List findings

Lists proven, exploitable findings for the organization, newest first. Defaults to open findings; narrow with the filters below.

Path parameters

parametertypedescription
id*integerThe organization id.

Query parameters

parametertypedescription
severitystringcritical | high | medium | low | info
statusstringDefaults to open. Use all for every status.
enginestringFilter by engine: code | web | deps | cloud | dns | contract.
typestringFilter by vulnerability type / rule id (e.g. H001).
updated_sincestringISO timestamp. Only findings changed since then — poll this to sync.
limitintegerPage size (default 25, max 100).
offsetintegerSkip this many results for pagination (default 0).

Returns

A 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"
example response
{
  "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
}
GET/findings/:id

Retrieve a finding

Returns one finding in full detail: the proof, the exact request that triggers it, an AI read on the blast radius, and the recommended fix. The finding must belong to the key's org.

Path parameters

parametertypedescription
id*integerThe finding id.

Returns

The finding object with proof, locations, and AI assessment.
curl https://api.mustersecurity.com/findings/4012 \
  -H "Authorization: Bearer $MUSTER_API_KEY"
example response
{
  "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"
}
PATCH/findings/:id

Update a finding

Triage a finding by setting its status. Mark it resolved once you've shipped the fix, acknowledged while you work on it, or false_positive. This is what closes the loop when fixing from an editor. Requires a member+ key.

Path parameters

parametertypedescription
id*integerThe finding id.

Body parameters

parametertypedescription
status*stringOne of open, acknowledged, resolved, false_positive.
notestringOptional. Recorded on the finding as an audit trail (e.g. "fixed in PR #142").

Returns

The finding's 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"}'
example response
{ "id": 4012, "status": "resolved" }
PATCH/orgs/:id/findings

Bulk update findings

Triage many findings at once by setting one status on all of them, for example to mark a batch of noise as false_positive. Ids that belong to another organization, or are already at that status, are skipped, and the response tells you how many actually changed, so repeating a call is safe. One call counts as one request against the rate limit. Requires a member+ key and a paid plan.

Path parameters

parametertypedescription
id*integerThe organization id.

Body parameters

parametertypedescription
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*stringOne of open, acknowledged, resolved, false_positive.
notestringOptional. Recorded on each finding that changed as an audit trail. Up to 2,000 characters; longer notes are truncated.

Returns

The 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"}'
example response
{
  "status": "false_positive",
  "requested": 3,
  "updated": 2,
  "updated_ids": [4012, 4020]
}
POST/orgs/:id/scan

Launch scans

Kicks off scans for the organization. Pass asset_ids to scan just those assets; otherwise all re-scans everything and the default scans only never-scanned assets. Requires a member+ key.

Path parameters

parametertypedescription
id*integerThe organization id.

Body parameters

parametertypedescription
asset_idsinteger[]Scan only these assets (ids from /orgs/:id/assets). Takes precedence over all.
allbooleanRe-scan every asset. Omit to scan only never-scanned assets.

Returns

Counts of 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]}'
example response
{ "launched": 3, "skipped": 0, "errors": [] }
GET/orgs/:id/scans

List scans

Lists recent scan runs for the organization, newest first, each with its status and how many findings it produced. Poll this after launching a scan to know when results are in.

Path parameters

parametertypedescription
id*integerThe organization id.

Query parameters

parametertypedescription
limitintegerPage size (default 25, max 100).
offsetintegerSkip this many results for pagination (default 0).

Returns

A 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"
example response
{
  "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
}
GET/scans/:id

Retrieve a scan

Returns one scan's status and findings count. The status moves from pending → running → success (or error). The scan must belong to the key's org.

Path parameters

parametertypedescription
id*integerThe scan id.

Returns

The scan object with its current status and findings count.
curl https://api.mustersecurity.com/scans/88 \
  -H "Authorization: Bearer $MUSTER_API_KEY"
example response
{
  "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"
}
GET/orgs/:id/summary

Organization summary

Security posture at a glance: the current score, open findings broken down by severity, asset count, and when anything was last scanned. One call, no paging — ideal for a status badge or CI gate.

Path parameters

parametertypedescription
id*integerThe organization id.

Returns

Score, open_findings, open_by_severity, assets, and last_scanned_at.
curl https://api.mustersecurity.com/orgs/1/summary \
  -H "Authorization: Bearer $MUSTER_API_KEY"
example response
{
  "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 shape
{ "error": "This key isn't scoped to that organization.", "code": "forbidden_org_scope" }
parametertypedescription
200successRequest succeeded.
400 · invalid_requesterrorInvalid parameters (e.g. an unknown status value).
401 · unauthorizederrorMissing or invalid API key.
402 · upgrade_requirederrorFindings data and triage require a paid plan.
403 · forbidden_org_scopeerrorThe key isn't scoped to that organization.
403 · forbidden_roleerrorThe key's role can't perform this action (needs member+).
404 · not_founderrorNo such organization, finding, or scan.
429 · rate_limitederrorToo 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.

parametertypedescription
X-RateLimit-LimitheaderRequests allowed in the current window.
X-RateLimit-RemainingheaderRequests left in the current window.
X-RateLimit-ResetheaderUnix 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.

idempotent request
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}'