> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matproof.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a finding

> Push a finding from an external scanner, audit, or custom check into Matproof's unified Findings view.

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](/features/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:

```bash theme={null}
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.


## OpenAPI

````yaml POST /v1/findings
openapi: 3.0.0
info:
  title: API Documentation
  description: The API documentation for this application
  version: '1.0'
  contact: {}
servers:
  - url: http://localhost:3333
    description: Local API Server
  - url: https://api.matproof.com
    description: API Server
security: []
tags: []
paths:
  /v1/findings:
    post:
      tags:
        - Findings
      summary: Create a finding
      description: Create a new finding for a task (Auditor or Platform Admin only)
      operationId: FindingsController_createFinding_v1
      parameters:
        - name: X-Organization-Id
          in: header
          description: >-
            Organization ID (required for session auth, optional for API key
            auth)
          required: false
          schema:
            type: string
      requestBody:
        required: true
        description: Finding data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFindingDto'
      responses:
        '201':
          description: The created finding
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Auditor or Platform Admin required
        '404':
          description: Task not found
      security:
        - apikey: []
components:
  schemas:
    CreateFindingDto:
      type: object
      properties:
        taskId:
          type: string
          description: Task ID this finding is associated with
          example: tsk_abc123
        type:
          type: string
          description: Type of finding (SOC 2 or ISO 27001)
          enum:
            - soc2
            - iso27001
          default: soc2
        templateId:
          type: string
          description: Finding template ID (optional)
          example: fnd_t_abc123
        content:
          type: string
          description: Finding content/message
          example: >-
            The uploaded evidence does not clearly show the Organization Name or
            URL.
          maxLength: 5000
      required:
        - taskId
        - type
        - content
  securitySchemes:
    apikey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication

````