Violations API reference

Report a violation

POST /v1/sdk/violations

Reports a single violation to Bissap Cloud. See Violations & enforcement for context.

Headers:

Authorization: Bearer <sdkSecret>
x-bissap-project: <projectId>

Body:

{
  "violation": {
    "apiKeyId": "uuid",
    "userId": "string (optional)",
    "intent": "string (optional)",
    "kind": "FORBIDDEN_SCOPE",
    "severity": "severe",
    "message": "Human-readable description (optional)",
    "metadata": {},
    "at": "2026-02-15T12:00:00Z (optional, defaults to now)"
  }
}

Response: { "ok": true }

List violations

GET /v1/sdk/violations

Returns violations for the authenticated project, with optional filters and pagination.

Headers:

Authorization: Bearer <sdkSecret>
x-bissap-project: <projectId>

Query parameters:

Parameter	Type	Default	Description
`keyId`	string		Filter by agent key ID
`kind`	string		Filter by violation kind
`severity`	string		Filter by severity (`info`, `warning`, `severe`)
`since`	string		ISO 8601 timestamp lower bound
`limit`	number	50	Results per page (max 200)
`offset`	number	0	Pagination offset

Response:

{
  "violations": [
    {
      "id": "uuid",
      "keyId": "uuid",
      "userId": "string | null",
      "intent": "string | null",
      "kind": "FORBIDDEN_SCOPE",
      "severity": "severe",
      "message": "string | null",
      "metadata": {},
      "createdAt": "2026-02-15T12:00:00.000Z"
    }
  ],
  "total": 42
}

Results are ordered by createdAt descending (newest first).

Error responses:

401 UNAUTHORIZED if SDK auth headers are missing or invalid
400 VALIDATION_ERROR if severity filter is not one of info, warning, severe

Intents manifest Changelog