Incident Intelligence

POST https://kovca.io/api/v1/incidents/triage

Authenticate with your API key in the Authorization: Bearer header. Send JSON with Content-Type: application/json; bodies are limited to 16 KB.

Metric thresholds and your severity policy are applied exactly in code. The incident report is interpreted to classify the symptom and judge impact. Kovca never invents a root cause, never confirms a security incident, and never pages anyone or changes your systems.

Request body

{
  "title": "Checkout API returning 503s",
  "description": "Since 14:05 UTC most checkout requests fail with 503 Service Unavailable. Customers can't complete orders.",
  "affected_services": [
    {
      "name": "checkout-api",
      "criticality": "critical"
    }
  ],
  "customer_impact": {
    "affected_percent": 82,
    "revenue_impacting": true
  },
  "metrics": [
    {
      "name": "error_rate",
      "value": 81.5,
      "threshold": 5,
      "breach_when": "above",
      "unit": "%"
    },
    {
      "name": "p95_latency",
      "value": 420,
      "threshold": 800,
      "breach_when": "above",
      "unit": "ms"
    }
  ],
  "severity_policy": {
    "rules": [
      {
        "severity": "critical",
        "min_affected_percent": 50,
        "service_criticality": [
          "critical"
        ]
      },
      {
        "severity": "critical",
        "incident_types": [
          "security"
        ]
      },
      {
        "severity": "high",
        "revenue_impacting": true
      },
      {
        "severity": "high",
        "min_affected_percent": 10
      },
      {
        "severity": "medium",
        "metric_breach": true
      }
    ],
    "default_severity": "low"
  }
}

Response

{
  "request_id": "req_Kw3nR7tLm1VqB5zP",
  "incident_type": "availability",
  "severity": "critical",
  "severity_basis": "policy",
  "matched_policy_rule": 0,
  "requires_escalation": true,
  "recommended_action": "activate_incident_response",
  "signals": [
    "metric_threshold_breached",
    "service_unavailable",
    "critical_service_affected",
    "revenue_impact"
  ],
  "breached_metrics": [
    "error_rate"
  ],
  "missing_information": []
}

Incident types

• availability: A service, feature, or endpoint is down or unreachable, or requests fail outright.
• performance: The service works but is slow, degraded, or timing out for some requests.
• security: Possible unauthorized access, credential exposure, data leakage, malware, or suspicious activity.
• data_integrity: Data is wrong, missing, duplicated, or corrupted.
• integration_failure: A connection to a third-party or internal dependency fails, such as a payment provider, webhook, or sync job.
• configuration: A change to settings, deployment, certificates, DNS, or feature flags caused the problem.
• other: None of the above.

Recommended actions (first match wins)

• escalate / activate_incident_response: A possible security incident: activate_incident_response if critical, otherwise escalate.
• investigate: Contradictory telemetry behind a provisional severity, or a medium severity.
• activate_incident_response: Critical severity.
• escalate: High severity.
• request_information: No customer impact or metrics were sent for a low or medium incident.
• monitor: Low severity.

Without a severity policy

{
  "title": "Unusual admin logins",
  "description": "We see successful admin logins from an unfamiliar country at 03:00 for two accounts, followed by an export of the customer list.",
  "affected_services": [
    {
      "name": "admin-console",
      "criticality": "high"
    }
  ]
}

Code

curl https://kovca.io/api/v1/incidents/triage \
  -H "Authorization: Bearer $KOVCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Checkout API returning 503s",
  "description": "Since 14:05 UTC most checkout requests fail with 503 Service Unavailable. Customers can'\''t complete orders.",
  "affected_services": [
    {
      "name": "checkout-api",
      "criticality": "critical"
    }
  ],
  "customer_impact": {
    "affected_percent": 82,
    "revenue_impacting": true
  },
  "metrics": [
    {
      "name": "error_rate",
      "value": 81.5,
      "threshold": 5,
      "breach_when": "above",
      "unit": "%"
    },
    {
      "name": "p95_latency",
      "value": 420,
      "threshold": 800,
      "breach_when": "above",
      "unit": "ms"
    }
  ],
  "severity_policy": {
    "rules": [
      {
        "severity": "critical",
        "min_affected_percent": 50,
        "service_criticality": [
          "critical"
        ]
      },
      {
        "severity": "critical",
        "incident_types": [
          "security"
        ]
      },
      {
        "severity": "high",
        "revenue_impacting": true
      },
      {
        "severity": "high",
        "min_affected_percent": 10
      },
      {
        "severity": "medium",
        "metric_breach": true
      }
    ],
    "default_severity": "low"
  }
}'

Errors

• 400 INVALID_REQUEST: a field is missing, too long, the wrong type, or not allowed. The message names the field.
• 413 PAYLOAD_TOO_LARGE: the body is larger than 16 KB.
• 401 UNAUTHORIZED, 429 RATE_LIMITED, 503 SERVICE_UNAVAILABLE, 504 TIMEOUT: see Errors and limits.

Limitations

• Without a severity_policy, severity is provisional: an interpretation of the impact you report, not your organization's definition.
• possible_security_incident means the report shows signs worth escalating, not that an incident is confirmed.
• The API doesn't read your monitoring systems; it uses only the metrics you send.
• Request data is processed to produce the result and is not stored by Kovca.