Skip to Content
APISuppressions

Suppressions API

Manage finding suppressions for baseline management and exception handling.

Suppressions require organization context. Personal workspace suppressions use the user’s default organization.

Create Suppression

Suppresses a finding so it won’t appear in future scans or diff comparisons.

POST /v1/orgs/{org_id}/suppressions
Authorization: Bearer {token}
Content-Type: application/json

Request Body

{
  "pattern_id": "universal_prompt_injection",
  "agent_id": "agent_abc123",
  "file_path": "agent/handlers/chat.py",
  "line_number": 42,
  "finding_hash": "sha256:a1b2c3d4e5f6...",
  "reason": "accepted_risk",
  "justification": "Input sanitized by upstream middleware. See security review SEC-2025-042.",
  "expires_at": "2026-06-01T00:00:00Z"
}

Request Fields

FieldTypeRequiredDescription
pattern_idstringYesThe detection pattern ID to suppress
agent_idstringNoScope to specific agent (null = all agents)
file_pathstringNoScope to specific file (null = all files)
line_numberintegerNoScope to specific line
finding_hashstringNoExact finding hash for precise matching
reasonstringYesOne of: false_positive, accepted_risk, wont_fix, mitigated
justificationstringNoExplanation for audit trail (recommended)
expires_atISO 8601NoAuto-expire date (null = permanent)

Reason Values

ReasonUse When
false_positiveInkog incorrectly flagged safe code
accepted_riskRisk acknowledged, business decision to accept
wont_fixKnown issue that won’t be addressed
mitigatedCompensating controls reduce the risk

Response

{
  "id": "supp_abc123def456",
  "pattern_id": "universal_prompt_injection",
  "agent_id": "agent_abc123",
  "file_path": "agent/handlers/chat.py",
  "line_number": 42,
  "finding_hash": "sha256:a1b2c3d4e5f6...",
  "reason": "accepted_risk",
  "justification": "Input sanitized by upstream middleware. See security review SEC-2025-042.",
  "expires_at": "2026-06-01T00:00:00Z",
  "created_at": "2025-12-28T10:30:00Z",
  "created_by": {
    "id": "user_xyz789",
    "email": "alice@acme.com"
  }
}

Errors

StatusCodeDescription
400invalid_reasonReason must be one of the valid values
400invalid_patternPattern ID does not exist
403insufficient_roleRequires Admin or Owner role
409already_suppressedActive suppression already exists for this scope

List Suppressions

Returns active suppressions for an organization.

GET /v1/orgs/{org_id}/suppressions
Authorization: Bearer {token}

Query Parameters

ParameterTypeDefaultDescription
agent_idstring-Filter by agent
pattern_idstring-Filter by pattern
reasonstring-Filter by reason
file_pathstring-Filter by file path prefix
include_expiredbooleanfalseInclude expired suppressions
include_revokedbooleanfalseInclude revoked suppressions
limitinteger50Max results (1-200)
offsetinteger0Pagination offset

Response

{
  "suppressions": [
    {
      "id": "supp_abc123def456",
      "pattern_id": "universal_prompt_injection",
      "pattern_title": "Prompt Injection Vulnerability",
      "agent_id": "agent_abc123",
      "agent_name": "customer-service-agent",
      "file_path": "agent/handlers/chat.py",
      "line_number": 42,
      "finding_hash": "sha256:a1b2c3d4e5f6...",
      "reason": "accepted_risk",
      "justification": "Input sanitized by upstream middleware.",
      "expires_at": "2026-06-01T00:00:00Z",
      "created_at": "2025-12-28T10:30:00Z",
      "created_by": {
        "id": "user_xyz789",
        "email": "alice@acme.com",
        "name": "Alice Smith"
      }
    }
  ],
  "total": 23,
  "has_more": false
}

Get Suppression

Returns details for a specific suppression.

GET /v1/orgs/{org_id}/suppressions/{suppression_id}
Authorization: Bearer {token}

Response

{
  "id": "supp_abc123def456",
  "pattern_id": "universal_prompt_injection",
  "pattern_title": "Prompt Injection Vulnerability",
  "pattern_severity": "HIGH",
  "agent_id": "agent_abc123",
  "agent_name": "customer-service-agent",
  "file_path": "agent/handlers/chat.py",
  "line_number": 42,
  "finding_hash": "sha256:a1b2c3d4e5f6...",
  "reason": "accepted_risk",
  "justification": "Input sanitized by upstream middleware. See security review SEC-2025-042.",
  "expires_at": "2026-06-01T00:00:00Z",
  "is_active": true,
  "created_at": "2025-12-28T10:30:00Z",
  "created_by": {
    "id": "user_xyz789",
    "email": "alice@acme.com",
    "name": "Alice Smith"
  },
  "updated_at": "2025-12-28T10:30:00Z",
  "revoked_at": null,
  "revoked_by": null
}

Revoke Suppression

Revokes an active suppression. The finding will appear in future scans.

DELETE /v1/orgs/{org_id}/suppressions/{suppression_id}
Authorization: Bearer {token}

Requires Admin or Owner role, or being the original creator.

Response

{
  "id": "supp_abc123def456",
  "revoked_at": "2025-12-28T11:00:00Z",
  "revoked_by": {
    "id": "user_xyz789",
    "email": "alice@acme.com"
  }
}

Suppressions are soft-deleted for audit purposes. The record remains in the database with revoked_at set.

Check Suppression

Checks if a specific finding would be suppressed.

POST /v1/orgs/{org_id}/suppressions/check
Authorization: Bearer {token}
Content-Type: application/json

Request Body

{
  "pattern_id": "universal_prompt_injection",
  "agent_id": "agent_abc123",
  "file_path": "agent/handlers/chat.py",
  "line_number": 42,
  "finding_hash": "sha256:a1b2c3d4e5f6..."
}

Response (Suppressed)

{
  "is_suppressed": true,
  "suppression": {
    "id": "supp_abc123def456",
    "reason": "accepted_risk",
    "justification": "Input sanitized by upstream middleware.",
    "expires_at": "2026-06-01T00:00:00Z",
    "created_by": {
      "email": "alice@acme.com"
    }
  }
}

Response (Not Suppressed)

{
  "is_suppressed": false,
  "suppression": null
}

Bulk Create Suppressions

Creates multiple suppressions in a single request.

POST /v1/orgs/{org_id}/suppressions/bulk
Authorization: Bearer {token}
Content-Type: application/json

Request Body

{
  "suppressions": [
    {
      "pattern_id": "universal_hardcoded_credentials",
      "file_path": "tests/fixtures/",
      "reason": "false_positive",
      "justification": "Test fixtures with fake credentials"
    },
    {
      "pattern_id": "universal_missing_rate_limits",
      "reason": "mitigated",
      "justification": "Rate limiting handled by API gateway"
    }
  ]
}

Response

{
  "created": [
    {
      "id": "supp_abc123",
      "pattern_id": "universal_hardcoded_credentials",
      "status": "created"
    },
    {
      "id": "supp_def456",
      "pattern_id": "universal_missing_rate_limits",
      "status": "created"
    }
  ],
  "errors": []
}

Export Suppressions

Exports suppressions in CSV format for review.

GET /v1/orgs/{org_id}/suppressions/export
Authorization: Bearer {token}
Accept: text/csv

Response

id,pattern_id,agent_id,file_path,line_number,reason,justification,expires_at,created_at,created_by
supp_abc123,universal_prompt_injection,agent_xyz,agent/chat.py,42,accepted_risk,"Input sanitized",2026-06-01,2025-12-28,alice@acme.com

Suppression Statistics

Returns suppression statistics for an organization.

GET /v1/orgs/{org_id}/suppressions/stats
Authorization: Bearer {token}

Response

{
  "total_active": 23,
  "total_expired": 5,
  "total_revoked": 12,
  "by_reason": {
    "false_positive": 8,
    "accepted_risk": 10,
    "wont_fix": 3,
    "mitigated": 2
  },
  "by_pattern": {
    "universal_prompt_injection": 5,
    "universal_hardcoded_credentials": 8,
    "universal_missing_rate_limits": 4,
    "other": 6
  },
  "expiring_soon": 3,
  "expiring_soon_threshold_days": 30
}
Last updated on
OrganizationsFeedback & Calibration