Skip to main content
POST
/
v1
/
findings
Create a finding
curl --request POST \
  --url http://localhost:3333/v1/findings \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "taskId": "tsk_abc123",
  "type": "soc2",
  "content": "The uploaded evidence does not clearly show the Organization Name or URL.",
  "templateId": "fnd_t_abc123"
}
'
Use this endpoint to push findings from any source that doesn’t have a native Matproof integration — a custom security scanner, a CI/CD pipeline check, an internal-audit ticketing system, a manual entry from a board meeting. Pushed findings appear in the unified Findings view alongside findings from internal audits, pen-tests, the device agent, and connected integrations.

​
Common use cases

  • Custom security scanner — pipe results from a scanner that isn’t on the integrations list (Trivy, Grype, custom SAST)
  • CI/CD pipeline — fail-the-build checks generate findings that are tracked through to remediation
  • Manual escalation — issues raised in board / management meetings logged formally
  • Bridging external GRC — mirror findings from a parent-org GRC tool into a subsidiary’s Matproof tenant

​
Idempotency

Always send Idempotency-Key on POST /v1/findings — most use cases retry on transient failure, and you don’t want duplicate findings: 
curl -X POST https://api.matproof.com/v1/findings \
  -H "X-API-Key: ..." \
  -H "Idempotency-Key: aikido-issue-12345-2026-05-08" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Vulnerable npm package: lodash@4.17.20",
    "severity": "high",
    "source": "external-scanner",
    "description": "CVE-2021-23337 affects production builds. Fix: upgrade to lodash@4.17.21+",
    "linkedControlIds": ["ctrl_iso27001_a8_8"]
  }'
The Idempotency-Key should encode the originating system’s stable identifier — for the Aikido example above, aikido-issue-{aikido_issue_id} — so retries always resolve to the same Matproof finding.

​
Linked controls

When linkedControlIds is provided, the finding immediately appears on those controls’ Findings tabs and contributes to the framework’s compliance-score calculation. Multiple controls can be linked when a single finding affects multiple frameworks.

​
Severity values

informational / low / medium / high / critical For external scanners, map their severity scale to Matproof’s: most scanners use 0–10 CVSS, where 7+ → high and 9+ → critical.

​
Response

On success, the response includes the created finding’s id. Store this in your originating system to support future updates (PATCH /v1/findings/{id}) — for example, when the underlying scanner reports the issue resolved.

Authorizations

​
X-API-Key
string
header
required

API key for authentication

Headers

​
X-Organization-Id
string

Organization ID (required for session auth, optional for API key auth)

Body

application/json

Finding data

​
taskId
string
required

Task ID this finding is associated with

Example:

"tsk_abc123"

​
type
enum<string>
default:soc2
required

Type of finding (SOC 2 or ISO 27001)

Available options:
soc2,
iso27001
​
content
string
required

Finding content/message

Maximum string length: 5000
Example:

"The uploaded evidence does not clearly show the Organization Name or URL."

​
templateId
string

Finding template ID (optional)

Example:

"fnd_t_abc123"

Response

The created finding